Rollbase User Guide 5 3 2 PDF
Uploaded by
HerbertRollbase User Guide 5 3 2 PDF
Uploaded by
Herbert® ®
Progress Rollbase User's Guide
Copyright
© 2018 Progress Software Corporation and/or one of its subsidiaries or affiliates. All rights reserved.
These materials and all Progress® software products are copyrighted and all rights are reserved by Progress
Software Corporation. The information in these materials is subject to change without notice, and Progress
Software Corporation assumes no responsibility for any errors that may appear therein. The references in these
materials to specific platforms supported are subject to change.
Corticon, DataDirect (and design), DataDirect Cloud, DataDirect Connect, DataDirect Connect64, DataDirect
XML Converters, DataDirect XQuery, DataRPM, Deliver More Than Expected, Icenium, Kendo UI, NativeScript,
OpenEdge, Powered by Progress, Progress, Progress Software Developers Network, Rollbase, SequeLink,
Sitefinity (and Design), SpeedScript, Stylus Studio, TeamPulse, Telerik, Telerik (and Design), Test Studio, and
WebSpeed are registered trademarks of Progress Software Corporation or one of its affiliates or subsidiaries
in the U.S. and/or other countries. Analytics360, AppServer, BusinessEdge, DataDirect Spy, SupportLink,
DevCraft, Fiddler, JustAssembly, JustDecompile, JustMock, Kinvey, NativeScript Sidekick, OpenAccess,
ProDataSet, Progress Results, Progress Software, ProVision, PSE Pro, Sitefinity, SmartBrowser,
SmartComponent, SmartDataBrowser, SmartDataObjects, SmartDataView, SmartDialog, SmartFolder,
SmartFrame, SmartObjects, SmartPanel, SmartQuery, SmartViewer, SmartWindow, and WebClient are
trademarks or service marks of Progress Software Corporation and/or its subsidiaries or affiliates in the U.S.
and other countries. Java is a registered trademark of Oracle and/or its affiliates. Any other marks contained
herein may be trademarks of their respective owners.
Please refer to the Release Notes applicable to the particular Progress product release for any third-party
acknowledgements required to be provided in the documentation associated with the Progress product.
Updated: 2018/09/28
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 3
Copyright
4 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Contents
Table of Contents
Chapter 1: Welcome.....................................................................................19
Chapter 2: Introduction to Progress Rollbase..........................................21
Supported browsers and platforms.......................................................................................................23
Obtaining an account............................................................................................................................23
Logging in...................................................................................................................................24
Updating your profile and logging out........................................................................................24
Selecting and modifying your security questions.......................................................................24
Switching tenants.......................................................................................................................25
Basic Rollbase concepts.......................................................................................................................26
Navigating the Rollbase environment...................................................................................................27
Application page components....................................................................................................30
Setup and setup page components...........................................................................................36
The Rollbase application............................................................................................................39
Search........................................................................................................................................39
Printing and PDF generation......................................................................................................45
Sample applications..............................................................................................................................48
Chapter 3: What's New in Rollbase 5.3......................................................51
What's New in RollBase 5.2..................................................................................................................56
What's New in Rollbase 5.1..................................................................................................................63
What's New in Rollbase 5.0..................................................................................................................66
Upgrading Private Cloud to Version 5.x................................................................................................70
Upgrading Private Cloud to Version 4.X...............................................................................................72
Chapter 4: Designing a Rollbase application............................................75
Application foundation...........................................................................................................................76
Object definition overview..........................................................................................................77
Object attributes.........................................................................................................................79
Relationships..............................................................................................................................80
Business logic and customizing the user experience...........................................................................81
Rollbase user interface components..........................................................................................81
Setting up accounts for testing............................................................................................................102
Distribution options.............................................................................................................................102
Chapter 5: Laying the foundation.............................................................105
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 5
Contents
Getting started with the Quick Create wizard......................................................................................106
Creating and managing applications...................................................................................................108
Creating an application your way.............................................................................................108
Editing applications..................................................................................................................109
Deleting an application.............................................................................................................124
Installing applications...............................................................................................................124
Creating and managing objects, fields, and relationships...................................................................128
Creating a new object definition...............................................................................................129
Creating a tab...........................................................................................................................130
Viewing and editing an Object Definition..................................................................................132
Deleting an object definition.....................................................................................................141
Views...................................................................................................................................................142
View controls............................................................................................................................142
Editing a view component........................................................................................................145
Setting the default view on a record list page..........................................................................146
Relationships between objects...........................................................................................................148
Global relationship lookup field properties...............................................................................149
Changing lookup field behavior................................................................................................149
Restricting records for lookup fields.........................................................................................152
Related records components...................................................................................................154
Related grid controls................................................................................................................154
Orphan records........................................................................................................................156
Working with records...........................................................................................................................156
Cloning records........................................................................................................................157
Protecting records....................................................................................................................159
Converting records...................................................................................................................160
Comparing and merging records..............................................................................................165
Auditing....................................................................................................................................169
Sending email..........................................................................................................................171
Transferring owners.................................................................................................................173
Updating multiple records........................................................................................................174
Tagging records........................................................................................................................179
Record Validation.....................................................................................................................181
Chapter 6: Adding business logic ...........................................................183
Working with templates.......................................................................................................................184
HTML and Script components..................................................................................................185
Adding template fields and integration links to an object.........................................................188
Template token syntax.............................................................................................................188
Iterating through records..........................................................................................................196
Using EVAL blocks...................................................................................................................198
Creating a record name template.............................................................................................198
Email templates........................................................................................................................199
Document templates................................................................................................................201
6 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Contents
Communication logs.................................................................................................................206
Localization..............................................................................................................................206
New record template................................................................................................................206
Right to left support in templates..............................................................................................207
Formulas.............................................................................................................................................208
Writing and debugging formulas..............................................................................................209
Formula return types................................................................................................................210
Improved Formula Debugging..................................................................................................211
Examples of valid string tokens................................................................................................213
Using dates in formulas............................................................................................................213
Example using images to represent record status...................................................................214
Formula execution limits..........................................................................................................214
Group functions........................................................................................................................215
Typical mistakes in formulas....................................................................................................216
Triggers and workflows.......................................................................................................................217
Trigger overview.......................................................................................................................218
Workflow processes............................................................................................................................255
Workflow overview..............................................................................................................................256
Creating a workflow process....................................................................................................256
Editing and viewing a workflow process...................................................................................257
Working with the Workflow Designer........................................................................................258
Workflow Designer Interface....................................................................................................259
Designing a Workflow Process................................................................................................263
Approvals.................................................................................................................................273
Record queues.........................................................................................................................276
Automating business decisions with Corticon rules............................................................................277
Supported relationships for request mapping..........................................................................280
Supported relationships for response mapping........................................................................281
Supported data types and conversions....................................................................................283
Creating a Corticon Decision Service Trigger..........................................................................286
Overriding functions to provide custom behavior ....................................................................292
Example trigger mapping to related objects.............................................................................294
Example trigger mapping where response creates a record...................................................296
Reports, charts, and gauges...............................................................................................................299
Working with reports.................................................................................................................299
Working with charts..................................................................................................................343
Working with gauges................................................................................................................347
Multi-currency support........................................................................................................................349
Surveys and quizzes...........................................................................................................................352
Creating a survey.....................................................................................................................353
Enabling surveys on an existing object....................................................................................354
Adding questions to a survey ..................................................................................................356
Creating a question library.......................................................................................................357
Survey pages and links............................................................................................................358
Taking a survey........................................................................................................................359
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 7
Contents
Collecting survey answers.......................................................................................................359
Using surveys on portals..........................................................................................................359
Chapter 7: Customizing the user experience..........................................361
Pages, the page editor, and grid controls...........................................................................................362
Creating tabs and pages..........................................................................................................362
Managing object pages............................................................................................................364
Managing generic pages..........................................................................................................367
Editing pages...........................................................................................................................369
Using grid controls to manage multiple records.......................................................................383
Using buttons on pages...........................................................................................................393
Customizing the header and footer..........................................................................................395
Customizing application tabs and menus.................................................................................397
UI Blueprints........................................................................................................................................401
Setting a Different UI Blueprint on Mobile Devices.............................................................................403
App Preview........................................................................................................................................405
Adaptive user interface.......................................................................................................................408
Automatic adaptive features for different devices....................................................................409
Cards and card containers.......................................................................................................411
Tailoring page components and views to devices....................................................................428
Customizing field labels...........................................................................................................430
Responsive user interface..................................................................................................................431
Vertical and horizontal responsive design................................................................................433
Responsive page title and toolbar............................................................................................435
Responsive dashboard pages..................................................................................................436
Working with views..............................................................................................................................437
Creating and editing views.......................................................................................................437
Adding columns........................................................................................................................438
Sorting and grouping................................................................................................................439
Calculating values for columns................................................................................................441
Filtering views..........................................................................................................................442
Editing a view on an application page......................................................................................448
Working with themes...........................................................................................................................455
Record List Options, Mobile and Tablet Support ................................................................................457
Pagination Control, Responsive Image Fields, and Custom Reports.................................................465
Enhanced Smart Images, Notifications, and Others...........................................................................475
Improved Editing Capabilities.............................................................................................................481
Record View and Record Edit Page Toolbars.....................................................................................492
Performance Improvements................................................................................................................495
Improved Recycle Bin, Kendo UI Library, and Settings Record..........................................................500
Filtering Features and Notification for Pending Changes...................................................................503
Programmatic client-side customization.............................................................................................507
Custom CSS............................................................................................................................507
Personalizing CSS...................................................................................................................510
8 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Contents
Creating Custom Themes........................................................................................................512
HTML event handlers...............................................................................................................513
Rollbase AJAX APIs.................................................................................................................519
Rollbase portals..................................................................................................................................524
Creating a portal.......................................................................................................................526
Creating portal pages...............................................................................................................528
Creating a custom header and footer.......................................................................................537
Changing the main portal page................................................................................................539
Assigning pages to a portal......................................................................................................540
Portal security..........................................................................................................................540
Hosted files.........................................................................................................................................547
Managing hosted files..............................................................................................................547
Hosted file tokens.....................................................................................................................548
Using hosted file tokens...........................................................................................................549
Chapter 8: Supporting mobile users........................................................551
Using the Telerik Platform to create a mobile app..............................................................................552
Creating Progress Data Catalogs for use in the Telerik Platform.............................................553
Using the Views first approach.................................................................................................554
Creating a mobile app using Code and the Progress Data Service template..........................575
Mobile-Web enabled applications.......................................................................................................579
Chapter 9: Integrating with outside sources...........................................583
Creating Rollbase objects from OpenEdge Object Services..............................................................584
Limitations................................................................................................................................584
Supported data types...............................................................................................................585
Linking Rollbase external objects to OpenEdge data..............................................................586
Creating an application from OpenEdge data..........................................................................588
Using DataDirect Cloud to access external data................................................................................602
Calling Progress Corticon decision services from Rollbase................................................................605
Creating a Rollbase application from Microsoft Access......................................................................605
Uploading the MDB file............................................................................................................605
Creating objects from MDB tables...........................................................................................606
Mapping fields and creating records........................................................................................607
Reviewing results.....................................................................................................................611
Creating a Rollbase application from a Salesforce application...........................................................613
Migrating the application..........................................................................................................614
Using external tables as Rollbase objects..........................................................................................615
Using an external database and external objects for Private Cloud........................................615
Creating an external object from an external database table..................................................620
Importing data.....................................................................................................................................622
Compatible import data types..................................................................................................623
Importing for existing objects...................................................................................................624
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 9
Contents
Importing to create a new object..............................................................................................626
Importing related objects..........................................................................................................627
Deleting multiple records by importing a spreadsheet........................................................................628
Exporting from views and reports.......................................................................................................629
Integrating with Google applications...................................................................................................630
Enabling Google integration.....................................................................................................631
Incoming Gmail........................................................................................................................632
Outgoing Gmail........................................................................................................................634
Google spreadsheets...............................................................................................................634
Synchronizing with Google Calendar.......................................................................................634
Google Maps............................................................................................................................635
Using SOAP or REST to integrate with Rollbase................................................................................637
Limits on API calls....................................................................................................................638
Monitoring API calls.................................................................................................................638
Integrating apps using Cloud Data Objects........................................................................................639
Creating Progress Data Catalogs for external applications.....................................................640
Integrating with Microsoft Exchange Server.......................................................................................641
Chapter 10: Security and access control.................................................643
User authentication.............................................................................................................................644
Forgotten password.................................................................................................................645
Whitelist IP addresses..............................................................................................................645
Access control.....................................................................................................................................647
Role-based access control.......................................................................................................648
User-based access control.......................................................................................................662
Relationship-based permissions..............................................................................................664
Page versions..........................................................................................................................667
Location/department/function permissions...............................................................................669
User authentication and password management................................................................................680
Enabling an administrative user to log into a customer tenant...........................................................683
Enhanced hashing and encryption algorithms....................................................................................683
Security for portals..............................................................................................................................685
Enhanced Security and Authentication-related Features....................................................................685
Chapter 11: Publishing and distributing applications............................691
Using the Progress Rollbase Marketplace..........................................................................................692
Publishing to the Marketplace App...........................................................................................693
Enabling or disabling Marketplace in Rollbase Private Cloud..................................................695
Managing the Marketplace using the Marketplace application in Rollbase Private Cloud.......697
Distributing applications in XML format...............................................................................................703
Components included in an application XML file.....................................................................703
Use of original IDs....................................................................................................................705
Locking applications.................................................................................................................706
10 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Contents
Attaching seed records............................................................................................................707
Attaching authentication profiles..............................................................................................707
Testing and verifying application correctness...........................................................................708
Generating application XML.....................................................................................................708
Providing a test drive................................................................................................................709
Administrative management of published applications............................................................710
Troubleshooting published applications..............................................................................................710
Chapter 12: Advanced setup and administration...................................713
Profile Settings options.......................................................................................................................713
My Settings..............................................................................................................................714
My Third Party Settings............................................................................................................715
My Localization Settings..........................................................................................................715
My Preferences........................................................................................................................716
My Security Settings................................................................................................................718
Change My Password..............................................................................................................718
Change API Credential............................................................................................................718
My Recycle Bin........................................................................................................................719
Administration setup...........................................................................................................................720
Configuring Administrative Preferences...................................................................................721
Transfer owners.......................................................................................................................726
Using company-wide settings..................................................................................................726
Backup and restore..................................................................................................................730
Currency formats......................................................................................................................732
Batch jobs................................................................................................................................736
Billing and support settings......................................................................................................738
Global text search....................................................................................................................738
Monitoring setup.................................................................................................................................738
Support................................................................................................................................................739
Language support...............................................................................................................................740
Adding support for other languages in Private Cloud..............................................................742
Translating applications............................................................................................................743
Enabling Google Apps for Rollbase Private Cloud.............................................................................753
Chapter 13: Installing and administering Private Cloud........................755
Introduction.........................................................................................................................................755
Platforms supported for Private Cloud.....................................................................................757
Licensing..................................................................................................................................758
OpenEdge license restrictions.................................................................................................758
Private Cloud updates..............................................................................................................758
Included Rollbase applications.................................................................................................758
Third party software you can install..........................................................................................759
Installation...........................................................................................................................................760
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 11
Contents
Prerequisites............................................................................................................................761
Using the Rollbase installer......................................................................................................761
Postrequisites...........................................................................................................................767
Using your own instance of Tomcat ........................................................................................767
Setting up Rollbase manually...................................................................................................768
Configuring a supported database...........................................................................................772
Configuring PD4ML..................................................................................................................776
Starting components and logging In.........................................................................................777
Activating your license.............................................................................................................778
Troubleshooting........................................................................................................................779
Administration.....................................................................................................................................781
System Tab Interface ..............................................................................................................782
Managing customer tenants.....................................................................................................823
Managing databases................................................................................................................832
Marketplace and Support Portal...............................................................................................835
Setting up ISV partners............................................................................................................836
Private Cloud security and access control..........................................................................................837
Supported Methods to Authenticate Users..............................................................................837
Security questions for authentication.......................................................................................866
Configuring Rollbase Private Cloud to use HTTPS..................................................................868
Multi-server environments...................................................................................................................868
Planning your multi-server architecture....................................................................................869
Configuring multiple instances of Rollbase components ........................................................875
Configuring high availability.....................................................................................................876
Migrating to a Rollbase Cluster Setup on AWS ......................................................................882
Deploying Rollbase on AWS....................................................................................................886
Installing NGINX.......................................................................................................................890
Configuring NGINX..................................................................................................................891
CDN Support.......................................................................................................................................896
Configuration file reference.................................................................................................................898
license.xml.........................................................................................................................898
node-config.json...............................................................................................................898
PAS command line reference.............................................................................................................900
The tcman command...............................................................................................................900
Manager actions.......................................................................................................................902
Server actions..........................................................................................................................913
General actions........................................................................................................................933
Chapter 14: Setup and administration for ISVs.......................................937
Getting started....................................................................................................................................938
System applications............................................................................................................................939
Creating a custom login page.............................................................................................................940
Creating a page for users to retrieve passwords................................................................................940
Customizing page title tags.................................................................................................................941
12 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Contents
Using a third-party cloud service for storage......................................................................................942
Using Amazon S3....................................................................................................................942
Using Microsoft Azure..............................................................................................................944
Using the ISV Partner application.......................................................................................................945
Creating and managing customer tenants...............................................................................946
Pushing application updates to other tenants.....................................................................................946
Installing application updates..............................................................................................................947
Version history and rolling back..........................................................................................................948
Chapter 15: Reference...............................................................................949
Server-side API...................................................................................................................................949
API error messages.................................................................................................................950
Query API.................................................................................................................................950
Object Script API......................................................................................................................973
User selection API....................................................................................................................988
Miscellaneous methods............................................................................................................991
Date, time, and currency API...................................................................................................997
PDF processing API...............................................................................................................1002
Hosted file API.......................................................................................................................1004
HTTP API...............................................................................................................................1005
XML processing API...............................................................................................................1011
JSON processing API............................................................................................................1012
Trigger to trigger API..............................................................................................................1013
Trigger environment API........................................................................................................1015
Debugging API.......................................................................................................................1019
Log API..................................................................................................................................1022
Email API...............................................................................................................................1024
User session data API............................................................................................................1027
Client-side AJAX API........................................................................................................................1032
Queries...................................................................................................................................1032
Field Manipulation..................................................................................................................1063
Data Formatting.....................................................................................................................1068
Grid Control Examples and API.............................................................................................1073
Miscellaneous........................................................................................................................1097
Display Functions...................................................................................................................1113
User session data..................................................................................................................1125
Client-side JavaScript.......................................................................................................................1131
Objects...................................................................................................................................1132
Functions................................................................................................................................1140
Properties...............................................................................................................................1144
Custom events.......................................................................................................................1154
Code Generator................................................................................................................................1156
Using the Code Generator.....................................................................................................1157
Metadata API and XML Reference...................................................................................................1158
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 13
Contents
Metadata XML reference........................................................................................................1158
SOAP Metadata Methods......................................................................................................1175
REST Metadata Methods.......................................................................................................1188
Rollbase REST Methods...................................................................................................................1201
appXML .................................................................................................................................1202
bulkCreate .............................................................................................................................1203
bulkCreateOrUpdate .............................................................................................................1204
bulkDelete .............................................................................................................................1205
bulkUpdate ............................................................................................................................1206
clearDataObjectCache...........................................................................................................1207
create ....................................................................................................................................1208
createArr................................................................................................................................1209
createCustomer .....................................................................................................................1211
create2 ..................................................................................................................................1212
createRecord..........................................................................................................................1213
delete ....................................................................................................................................1215
deleteArr ................................................................................................................................1215
deleteRecord..........................................................................................................................1216
getApplicationIds....................................................................................................................1217
getAuthentication...................................................................................................................1218
getBinaryData........................................................................................................................1219
getBuildStatus........................................................................................................................1221
getCodeById .........................................................................................................................1221
getCount ................................................................................................................................1222
getDataField ..........................................................................................................................1223
getDataObj ............................................................................................................................1225
getIdByCode .........................................................................................................................1227
getIdByOriginalId....................................................................................................................1228
getLDFIDs..............................................................................................................................1229
getPage .................................................................................................................................1230
getPermissionsByRole...........................................................................................................1231
getPermissionsByUser...........................................................................................................1233
getPicklist...............................................................................................................................1235
getRecord...............................................................................................................................1235
getRelationships ....................................................................................................................1237
getRoleById............................................................................................................................1239
getRoles.................................................................................................................................1240
getTopology............................................................................................................................1241
getUpdated ............................................................................................................................1243
install .....................................................................................................................................1244
installByAppId .......................................................................................................................1245
licenseUpdate........................................................................................................................1246
login........................................................................................................................................1246
logout.....................................................................................................................................1248
resetPassword.......................................................................................................................1248
14 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Contents
runAction................................................................................................................................1249
runTrigger ..............................................................................................................................1250
search ...................................................................................................................................1252
selectNumber ........................................................................................................................1253
selectQuery ...........................................................................................................................1253
selectValue ............................................................................................................................1255
setAuthentication....................................................................................................................1256
setBinaryData.........................................................................................................................1265
setDataField ..........................................................................................................................1267
setPermissionsByRole...........................................................................................................1268
setPermissionsByUser...........................................................................................................1270
update ...................................................................................................................................1271
updateArr...............................................................................................................................1272
updateCustomer ....................................................................................................................1273
updateRecord.........................................................................................................................1274
update2..................................................................................................................................1276
authenticationProfile - Create.................................................................................................1277
authenticationProfile - Edit.....................................................................................................1278
authenticationProfile - Delete.................................................................................................1279
getAllAuthenticationProfiles...................................................................................................1280
getAuthenticationProfileById..................................................................................................1291
mapAuthenticationToRole......................................................................................................1292
Rollbase CSS Styles for the Classic UI............................................................................................1293
Table Styles............................................................................................................................1293
Table Cell Styles.....................................................................................................................1295
Table Row Styles....................................................................................................................1298
Text Styles..............................................................................................................................1299
Page Editor Styles..................................................................................................................1300
Link Styles..............................................................................................................................1301
Sidebar Styles........................................................................................................................1301
Field types.........................................................................................................................................1302
Text field.................................................................................................................................1302
Text Area Field.......................................................................................................................1302
Checkbox Field......................................................................................................................1303
Decimal field...........................................................................................................................1303
Currency field.........................................................................................................................1303
Base Currency field................................................................................................................1304
Date Field...............................................................................................................................1304
Date/Time field.......................................................................................................................1304
Time field................................................................................................................................1304
Email Field.............................................................................................................................1305
Phone Number field...............................................................................................................1305
Password Field.......................................................................................................................1305
Integer field............................................................................................................................1306
Percent Field..........................................................................................................................1306
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 15
Contents
Picklist Field...........................................................................................................................1306
Picklist Multiselect..................................................................................................................1307
Radio Button Field..................................................................................................................1308
Group Checkbox Field...........................................................................................................1308
URL Field...............................................................................................................................1308
Auto-number Field..................................................................................................................1308
Auto-number Functional Changes.........................................................................................1310
File Upload field.....................................................................................................................1312
Image Upload field.................................................................................................................1312
Shared Image field.................................................................................................................1313
Formula Field.........................................................................................................................1313
Expression Field.....................................................................................................................1314
Roll-Up Summary Field..........................................................................................................1316
Template Field........................................................................................................................1316
Document Template Field......................................................................................................1317
Email Template Field..............................................................................................................1317
Related Field..........................................................................................................................1317
Integration Link Field..............................................................................................................1318
Dependent Picklist Field.........................................................................................................1318
Version Number Field.............................................................................................................1318
Reference Field......................................................................................................................1319
Advanced field properties.......................................................................................................1319
System Field Types................................................................................................................1320
Portal Field Types..................................................................................................................1322
Rollbase SOAP Methods..................................................................................................................1322
DataObj Container Class.......................................................................................................1323
DataField Container Class.....................................................................................................1324
SearchFilter Class .................................................................................................................1324
bulkCreate() ..........................................................................................................................1325
bulkCreateUpdate() ...............................................................................................................1326
bulkUpdate() ..........................................................................................................................1327
clearDataObjectCache().........................................................................................................1328
create() ..................................................................................................................................1328
createArr() .............................................................................................................................1329
createArr2() ...........................................................................................................................1331
createArrNoAudit() ................................................................................................................1332
createCustomer() ..................................................................................................................1333
createRecord().......................................................................................................................1333
delete() ..................................................................................................................................1334
deleteArr() .............................................................................................................................1335
deleteArrNoAudit().................................................................................................................1336
deleteRecord().......................................................................................................................1336
deleteRecords()......................................................................................................................1337
detailedSearch().....................................................................................................................1338
getBinaryData() .....................................................................................................................1339
16 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Contents
getCodebyId() .......................................................................................................................1340
getCount() .............................................................................................................................1340
getIdByCode() .......................................................................................................................1341
getDataField() .......................................................................................................................1342
getDataField2() .....................................................................................................................1343
getDataObj() ..........................................................................................................................1344
getExchangeRate() ...............................................................................................................1345
getPage() ..............................................................................................................................1345
getRelatedIDs()......................................................................................................................1347
getRelationships() .................................................................................................................1347
getRuntimeStatus() ...............................................................................................................1348
getUpdated() .........................................................................................................................1349
getRecord()............................................................................................................................1350
login().....................................................................................................................................1351
login2()...................................................................................................................................1351
logout() ..................................................................................................................................1352
resetPassword().....................................................................................................................1353
selectNumber() ......................................................................................................................1353
selectQuery() .........................................................................................................................1354
selectValue() ..........................................................................................................................1356
setBinaryData() .....................................................................................................................1357
setDataField() ........................................................................................................................1358
setDataField2() ......................................................................................................................1359
setExchangeRate() ...............................................................................................................1360
setRelationship() ...................................................................................................................1361
setRelatedIDs() .....................................................................................................................1362
textSearch() ...........................................................................................................................1363
update() .................................................................................................................................1363
updateArr() ............................................................................................................................1364
updateArrNoAudit()................................................................................................................1365
updateCustomer() .................................................................................................................1366
updateRecord()......................................................................................................................1367
Chapter 16: Getting help .........................................................................1369
Chapter 17: Third-party Acknowledgements.........................................1371
Rollbase Private Cloud Third-party Acknowledgements...................................................................1371
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 17
Contents
18 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
1
Welcome
Welcome to the Progress Rollbase product documentation!
® ®
The Rollbase product documentation provides an overview of the Rollbase Platform, information on how to
create, customize and distribute applications.
The entire documentation is grouped into different sections that help easily locate information pertaining to a
specific task that you intend to perform. Also, there are supporting sections which contain additional information
such as UI descriptions, APIs and so on, that may further help you in working with the Rollbase platform.
If you wish to skip reading the first few introductory topics on Rollbase platform and get started with creating
applications, the following table contains links to specific topics that provide you with a start point for a chosen
activity.
Upgrading Private Cloud to Version 5.x
Setting up Rollbase Manually
Creating an application
Installing an application
Editing an application
Deleting an application
Adding a new database
Creating an Authentication Profile
Creating a new object definition
Creating a tab
Viewing and editing an object definition
Adding fields
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 19
Chapter 1: Welcome
Creating a Workflow Process
Creating Triggers
Creating a Tabular Report
Running Reports
Publishing and Distributing Applications
Using the Progress Rollbase Marketplace
To quickly access information without browsing through the contents of the Product Documentation, you can
use the search feature.
Contact Info
Addresses of Progress Software Corporation offices in different geographical zones are available online at
® ®
https://www.progress.com/company/offices. For more information on Progress Rollbase , visit the web site
https://www.progress.com/rollbase.
20 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
2
Introduction to Progress Rollbase
Welcome to Progress Rollbase , a web-based platform for creating, customizing and distributing applications.
® ®
Rollbase applications run in an integrated online environment and share a common security model, data model
and user interface. Rollbase exemplifies Platform-as-a-Service (PaaS). There is no hardware or software to
buy or install, both developers and end-users access Rollbase using a web browser. Rollbase allows you to
focus on creating business value for users rather than on the expensive, complex and time-consuming tasks
of managing software and infrastructure.
The Rollbase development environment supports citizen developers and business users who want to create
custom applications. Its framework of wizards and dialogs provide drag-and-drop and point-and-click
convenience. You can create sophisticated applications without writing a line of code, but you also have the
option to use standards such as JavaScript and HTML to customize the logic and user interface. To get started,
you define a foundation for your app, by creating objects, their fields, and relationships between objects.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 21
Chapter 2: Introduction to Progress Rollbase
From the app foundation, Rollbase generates a starter set of pages that end users interact with to view, create,
update, and delete records. The following shows a few screens from an example application. The generated
pages are highly customizable.
The following image illustrates the typical process for developing Rollbase applications:
Rollbase offers a flexible and mature environment, suitable for the most demanding of applications:
• Platform options
22 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Supported browsers and platforms
Rollbase offers both hosted and Private Cloud environments. Private Cloud users install Rollbase components
on their own servers or on another cloud platform. Private Cloud users manage their own infrastructure,
while Progress manages the hosted cloud infrastructure for all hosted cloud users. For information on hosted
and Private Cloud, See www.progress.com/products/rollbase.
• Support for affiliates, resellers, and ISVs
Resellers and ISVs can use Progress Rollbase for developing and delivering custom SaaS Applications to
their customers. Rollbase provides white label programs for both hosted and private cloud customers. For
more information about working with Rollbase as a reseller or ISV, see Setup and administration for ISVs
on page 937
• Application Marketplace
The Rollbase Application Marketplace provides an online exchange where you can browse and install
ready-made applications such as a CRM system, a suite of integrated HR applications, a bug tracking
system, and others. Once a Rollbase application is installed, you can customize it to meet your specific
business needs.
• Get started quickly and learn by doing
The Rollbase Fast Track page contains links to the Quick Start tutorial, companion videos that demonstrate
basic Rollbase features, and links to related information in this documentation set. The tutorial helps you
exercise key Rollbase functionality and can be completed in about an hour. Check it out!
For details, see the following topics:
• Supported browsers and platforms
• Obtaining an account
• Basic Rollbase concepts
• Navigating the Rollbase environment
• Sample applications
Supported browsers and platforms
You can use any modern browser to access Rollbase, but Progress recommends use of one that we test
against. For Rollbase Private Cloud, you will also be interested in the supported operating systems and
databases. See Supported Platforms for the latest release.
Obtaining an account
On hosted Rollbase, the first person to sign up from a particular organization becomes an administrator of the
Rollbase tenant. (A tenant is a virtual space for creating and managing apps.) On Rollbase Private Cloud, the
person whose email address is entered during installation becomes the first administrator of the Private Cloud
tenant(s). Administrators can create user accounts, install applications from the Application Directory,
customize applications for specific business needs, and create applications.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 23
Chapter 2: Introduction to Progress Rollbase
Administrators create user accounts by adding User records. Each User record has a required User Role field.
Any Rollbase user with the Administrator role has complete administrative privileges. See Role-based access
control on page 648 for information about roles.
Private Cloud and ISV Partners have the option create multiple tenants, which they do by adding Customer
records. Therefore, the documentation often refers to these as customer tenants. Typically, those with the
ability to create tenants will want to use separate tenants for development and production. See Managing
customer tenants on page 823 for more information.
Logging in
Every User record has a required Email Address field. After an administrator creates a User record, the new
user will receive a confirmation email with a temporary password and a login URL. Progress recommends
changing passwords periodically. For Rollbase Private Cloud, administrators can require that passwords for
their tenant meet certain criteria, such as length and inclusion of numbers. See Configuring Password
Authentication on page 842 for more information.
For Rollbase Private Cloud, administrators can also require users to answer security questions as part of
logging in. When security questions are enabled, users will be prompted to select security questions and provide
the answers the next time they log in. Administrators create the questions, configure how many questions each
user can choose, and set the number of questions a user must answer when logging in. For example, an
administrator might create five security questions, require users to provide answers to three of the questions
as part of their profile, and require users to answer one of the questions when logging in.
See Security questions for authentication on page 866 for information about configuring security questions.
See Selecting and modifying your security questions on page 24 for details about managing the security
questions in your user profile.
Updating your profile and logging out
The page banner includes a drop-down menu next to the profile avatar:
The menu includes the following options:
• Update Profile — Opens the My Profile page where you can manage your personal settings and change
your password. See Profile Settings options on page 713 for details.
• Log Out — Logs you out of the system.
Selecting and modifying your security questions
If an administrator has configured security questions as part of the login process, you will be prompted to select
and answer questions the next time you log in. The questions and answers become part of your user profile.
At subsequent logins, you will be prompted to answer randomly selected security questions after entering the
correct login name and password. You can change the questions you want to answer and provide the answers
on the Change Password page.
24 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Obtaining an account
To change your selected security questions and answers to your user profile:
1. From the profile menu at the upper right corner of the browser, click Update Profile. The My Profile page
opens.
2. Click Change my Password. The Change Password page opens.
3. The Security Questions section allows you to select the number of questions you are required to answer
for your profile. Select each question from the drop-down and type your answer to each.
4. Click Save. The questions are now part of your user profile.
You can return to the Change Password page at any time to select a different set of questions or to change
your answers.
When you log in to Rollbase, you are prompted to answer a random list of security questions selected from
your user profile. You can optionally select the Remember this computer and skip security questions next
time I login check box. If checked, Rollbase sets a security cookie on your computer. If this cookie is present
when you log in to Rollbase the next time, the system will bypass the security questions. You should only use
this option on your personal computer.
Example: In the following graphic, the user has answered a single security question and checked the option
to remember this computer:
Switching tenants
On hosted Rollbase, you can switch to a different tenant if you have an account on that tenant with the same
email address. This is useful if your organization runs different applications on different tenants and you need
to access those applications.
To switch to a different tenant:
1. From the user profile, menu, select Switch Tenant. This option is only available if you have an account on
a different tenant.
The Switch Tenant dialog opens.
2. From the Switch Tenant dialog, select the tenant to which you want to switch. If you want this tenant to be
your default tenant, click Make Selected As Default. Click Switch Tenant to switch to that tenant.
You are now logged in to the other tenant.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 25
Chapter 2: Introduction to Progress Rollbase
Basic Rollbase concepts
Rollbase enables development and deployment of of browser-based Web apps and mobile apps. You first
create the Web app. Rollbase browser-based Web applications consist of a set of configurable components.
Core application components include objects, tabs and portals. Each of these core components contains
sub-components. The process of creating a Web application in Rollbase involves defining core components
and then building them out by adding and configuring sub-components. The Rollbase environment, whether
hosted or Private Cloud, transparently handles the data storage for Rollbase Web applications.
To provide a more specific mobile experience, you can:
• Take advantage of the Rollbase features that support multiple devices. Rollbase's responsive and adaptive
UI adapts to display nicely on a variety of devices, and you can configure specific devices to render
applications in a way that best suits each device.
• Expose objects to the Telerik Platform, where you can quickly build modern mobile apps that access Rollbase
data.
See Supporting mobile users on page 551 for more information on these options.
Rollbase capabilities
The Rollbase application development environment allows you to:
• Create an application data model by defining objects, fields, and relationships.
• Customize the user interface by modifying components such as pages, views, and templates, by adding
custom icons and logos, and by selecting themes for applications.
• Define and customize workflow processes, statuses, and actions.
• Develop automated programmatic business logic such as with triggers.
• Generate and process template-based documents in MS Word, MS Excel, HTML, and plain text email
formats.
• Enrich the user interface and workflow using client-side and server-side APIs.
• Use sophisticated full text search and filtering.
• Process data records using conversion mapping, comparison, parallel and sequential approvals, record
queuing, multi-currency support, and other built-in functionality.
• Use built-in survey capabilities to create quizzes or questionnaires.
• Schedule triggers to automate data processing.
• Use the built-in calendar for task and event management.
• Define portals to create external facing applications that integrate with your Rollbase applications and
seamlessly fit within existing websites and intranets.
• Secure your data using a number of authentication options and sophisticated access control.
• Enable integration with Google Apps: Gmail (outgoing and incoming), Spreadsheet, Calendar and Maps.
• Easily import your data and metadata from sources such as spreadsheets, Progress OpenEdge services,
and data exposed by Progress DataDirect Cloud or Microsoft Access.
• Easily migrate applications from Salesforce.com and the Force.com platform.
• Use SOAP or REST APIs to access or modify application data.
• Publish, distribute, and install any application built using Rollbase.
26 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Navigating the Rollbase environment
• Expose Rollbase objects to Telerik platform to create mobile apps with a customized user experience.
• ISV Partners can create and manage customer tenants to run their own SaaS business.
Navigating the Rollbase environment
In the Rollbase environment, screens and pages belong to one of two categories: application or setup. Each
Rollbase component has a definition, and a realization — the pages and behavior that are exposed to end
users. The Rollbase interface appears differently to different types of users. Only users with a role of Administrator
see screens that support development tasks such as creating and editing component definitions and customizing
the user interface. Application end users can only view applications, pages, and components that have been
exposed to them.
For example, the following screen shows an application definition, including its properties and its child
components:
You can easily switch between setup and application pages to test as you build. When the application is
complete, you expose the application to end users. See Distribution options on page 102 for more information.
You can choose one of two UI blueprints for an application's pages. A UI blueprint is how the application
navigation and various menus inside the application are rendered. The page content does not change across
blueprints. The available blueprints are:
• Traditional
• Modern - Vertical Menus
See UI Blueprints on page 401 for more information.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 27
Chapter 2: Introduction to Progress Rollbase
The following screen shows the resulting application interface using the Traditional UI blueprint.
The following screen shows the resulting application interface using the Modern - Vertical Menus UI blueprint.
28 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Navigating the Rollbase environment
You can control the way an application page renders a list of records on a particular type of device using cards
and card containers. The screen below shows the same application as above rendered using cards and card
containers on a smart phone.
See Cards and card containers on page 411 for more information.
The topics in this section cover functionality you will use frequently. Watch Finding your way around in Rollbase
for a short tour of the Rollbase interface.
See the following topics for details about the Rollbase interface:
• Application page components on page 30
• Setup and setup page components on page 36
• The Rollbase application on page 39
• Search on page 39
• Printing and PDF generation on page 45
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 29
Chapter 2: Introduction to Progress Rollbase
Application page components
When you create applications or add new object definitions to existing applications, Rollbase creates a set of
application pages for each of the objects you define. By default, Rollbase creates a page containing a list view
of all records for each object. The page also contains controls for creating, finding, viewing, editing, and deleting
object records. Page components are different depending on the type of device, which can be a desktop, tablet,
or smart phone. They are also different depending on the UI blueprint used. Each UI blueprint renders the page
components in a different way.
The following topics describe how page components are rendered in each UI blueprint.
Application pages contain the following components:
• The Rollbase Menu and Help on page 30
• The application tab and menu bar on page 32 (Traditional UI blueprint only)
• The Application Switcher on page 34 (Modern - Vertical Menus UI blueprint only)
• The Page Options menu on page 35 (desktop only)
• The customer logo (desktop only)
• The search button (desktop and tablet only)
Application pages that display list views also have a page menu (desktop only).
See Application page types on page 82 for a list of application page types.
The Rollbase Menu and Help
The Rollbase menu and the menu items appear in the application depending on the UI Blueprint selected for
the device in use.
Traditional UI Blueprint: The Rollbase menu icon appears on the top left corner of the application. Upon
clicking the Rollbase menu icon, all the menu items appear in a left navigational panel that works like an
accordion.
Modern - Vertical Menus, the Rollbase menu items and help are grouped differently for ease of use.
30 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Navigating the Rollbase environment
The Rollbase menu contains the following navigational controls:
• Getting Started — Launches a page with information and links to help you get started with developing
applications.
• Modern - Vertical Menus, this will appear under the help icon on top right of the application pages.
• Traditional, this will appear under the Rollbase menu.
• Online Help — Opens the Rollbase documentation.
• Modern - Vertical Menus, this will appear under the help icon on top right of the application pages.
• Traditional, this will appear under the Rollbase menu.
• Recent Items — Displays a list of recently viewed records, allowing quick access for editing. Each record's
object type appears in parentheses. Click the link to open the record. Administrative users also see recently
viewed application components. In both the UI Blueprints - Traditional and Modern - Vertical Menus, this
item appears within the Rollbase menu.
• My Recycle Bin — Opens the Rollbase My Recycle Bin, which stores all the records you have deleted
from your Rollbase instance. On the Recycle Bin page, you can review recycle bin data, filter deleted
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 31
Chapter 2: Introduction to Progress Rollbase
records in the recycle bin using Deleted By and Deleted At, and restore or purge (permanently remove)
selected recycle bin data.
Some data, such as uploaded files, cannot be restored. Rollbase permanently purges deleted records after
30 days.
In both the UI Blueprints - Traditional and Modern - Vertical Menus, this item appears within the Rollbase
menu.
• My Theme — Opens the My Theme layer on top of the application pages, allowing a user to select a theme
and apply it to all applications. See Selecting a theme for a user on page 122 for details. In both the UI
Blueprints - Traditional and Modern - Vertical Menus, this item appears within the Rollbase menu.
• Rollbase Forum — Opens the Rollbase Forum page in the Progress Communities site. From this page,
you can read existing forum threads, ask Rollbase questions, and access other Rollbase resources such
as customer support.
• Modern - Vertical Menus, this will appear under the Rollbase menu > Administration sub menu.
• Traditional, this will appear under the Rollbase menu.
For administrative users, the Rollbase menu offers the following controls, which appear under the Rollbase
menu in both Traditional and Modern - Vertical Menus UI Blueprints:
• New Application — Launches the Create a New Application wizard, from where you can quickly create
a new application with guided help or opt to create an application through Install from Marketplace, Create
from External Data, or Create from Existing Objects.
• Install Applications — Opens the Application Marketplace, where you can find and install ready-made
Rollbase applications.
• Setup Home — Opens the Setup Home page, where administrators can navigate to the administrative
and development pages. See Setup and setup page components on page 36 for more information.
• Subscription — Opens the Subscription page, displaying the Rollbase subscription details such as the
Current Plan, Your Resources, System Information, and Your Settings. One of the important pieces of
information on the page is your Customer ID.
Support Home, Privacy and Terms of Use - these menu items appear under the help icon on the top right
of the application pages only when the UI Blueprint selected is Modern - Vertical Menus. Clicking any of these
menu items leads the user to the relevant information on the Progress Website.
The application tab and menu bar
Application pages that use the Traditional UI blueprint contain an application tab and a menu bar:
The menu bar is responsive; if the screen size is too narrow to display all menu items, non-visible items are
added to an overflow menu.
Administrative users
By default, the application tab and menu bar provide the following menu items and controls to those with an
administrative role:
• Application switcher — A drop-down menu next to the application name that allows the user to navigate to
different applications and to setup pages. Select the App Settings button next to an application name to
navigate to the application's setup page.
32 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Navigating the Rollbase environment
• Application menu bar —Contains each tab and menu defined in the application. Administrators can click
plus to create a new object and/or tab for the application:
Note: Application tabs and menus are in the The Rollbase Menu and Help on page 30 (sidebar) for
applications that use the Modern - Vertical Menus UI blueprint.
Non-administrative users
By default, the application tab and menu bar provide the following menu items and controls to those with a
non-administrative role:
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 33
Chapter 2: Introduction to Progress Rollbase
• Application switcher — A drop-down menu on the application tab that allows the user to navigate to different
applications. Only applications the user has permission to access appear in the menu:
Note: The Application Switcher on page 34 is in a different location for applications that use the Modern -
Vertical Menus UI blueprint.
• Application menu bar — Contains each tab and menu defined in the application.
Note: Application tabs and menus are in the The Rollbase Menu and Help on page 30 (sidebar) for
applications that use the Modern - Vertical Menus UI blueprint.
See Application tabs and menus on page 91 for more information about tabs and menus.
The Application Switcher
The Application Switcher is available as a drop-down menu next to the application name irrespective of the
selected UI Blueprint, as depicted below:
The application switcher allows the user to navigate to different applications and to setup pages. Administrators
can select the App Settings button next to an application to navigate to the application's setup page.
Non-administrative users only see the applications to which they have access.
34 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Navigating the Rollbase environment
All setup pages contain the application switcher. The application switcher allows you to navigate to application
and setup pages in the following ways:
• App Settings — Opens the application settings for the current application.
• Setup Home — Opens the Setup home page.
• Rollbase — Opens the Rollbase application.
• Application name — Opens the main page for the selected application.
The Page Options menu
Access the Page Options by clicking the icon below search. The menu includes options for printing and PDF
generation as well as information about how long the page took to load and render. See Printing and PDF
generation on page 45 for more information. Administrators also have the Design This Page option, which
opens the page editor for the current page. The Page Options menu is only available on desktops.
The Tab Options menu
Application pages that list records have a page menu that allow a user to perform the following tasks. All tasks
operate on the currently displayed object type:
• Create a new record.
• Search records (desktop only)
• Import an XSL, XSLT, or CSV file to create, update, or delete records (desktop only)
• Create a template (desktop only)
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 35
Chapter 2: Introduction to Progress Rollbase
On tablets and smart phones, the page menu only allows users to create a new record. In addition, only
applications that use the Traditional UI blueprint have a page menu on tablets and smart phones.
Replacing the Progress logo
By default, application pages display the Progress logo in the upper-left corner.
You can replace this logo with your company logo for a single application or for all applications. See Editing
applications on page 109 for information about setting the logo for an application. See Account settings on page
727 for information about replacing the logo for all applications.
Setup and setup page components
Setup includes configuration for the following:
• Personal Setup — Preferences such as language, time zone, and Google app settings.
• Applications Setup — Definitions for applications and application components.
• Administration Setup — Global settings for the tenant and user and role management.
• Monitoring — Monitoring settings for runtime status and systems logs.
Users with an administrative role can configure personal, application, and account settings from the Setup
home page. Users without administrative privileges can only configure their personal settings using the Update
Profile option in the user profile menu.
Administrators can access the Setup home page from an application page in the following ways:
• Select Settings from the Rollbase menu.
• Select Setup Home from the application switcher.
• If you are already on a setup page, select Setup Home from the application switcher:
36 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Navigating the Rollbase environment
The following is the Setup home page of hosted Rollbase:
All setup pages contain the following navigational components:
• The Application Switcher on page 34
• The left navigation pane on page 38
• Search on page 39
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 37
Chapter 2: Introduction to Progress Rollbase
The left navigation pane
All setup pages include the left navigation pane, which allows administrators to create and install applications,
navigate to recently visited pages, and manage the Recycle Bin:
38 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Navigating the Rollbase environment
The Rollbase application
The Rollbase application gives administrators access to the calendar, including meetings and to-do items, to
reports, to user accounts, and to Gmail messages (if their Google account is attached). By default, the Rollbase
application uses the Modern - Vertical Menus UI blueprint. The following graphic shows the Rollbase application's
Home page:
For information about working with the Rollbase calendar, see The Rollbase calendar on page 96.
For information about attaching a Google account, see Integrating with Google applications on page 630.
Search
The search button at the top right of the screen allows you to search your tenant. To set the scope of a search,
use the drop-down menu to select Metadata, an object type or all object types. Administrators can search all
metadata.
The simplest way to search for data is to select the scope of the search and type a single term into the search
box.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 39
Chapter 2: Introduction to Progress Rollbase
When you click the search button on an application page, the following fields open. By default, the scope of a
search is set to Metadata:
The search fields are always available on a setup page:
Object fields have a property that specifies whether or not to Index this Field as part of the text search
engine. If none of an object's fields has this property checked, that object will not appear in the drop-down
menu. See Advanced field properties on page 1319 for more information.
Search queries in Rollbase are broken up into terms and operators. There are two types of terms: single terms
and phrases:
• A single term is a single word, such as Sales or Marketing.
• A phrase is a group of words surrounded by double quotes, such as "Human Resources".
Rollbase supports advanced search syntax such as wildcard character searches and the ability to combine
multiple terms together with Boolean operators to form more complex queries.
Note: By default, a user will have permission to view the search button. However, if uers with a
non-administrative role are not granted the Search Box permission, they cannot view the search button. See
Roles and permissions on page 648 for more information.
40 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Navigating the Rollbase environment
Wildcard character searches
Rollbase supports single and multiple character wildcard character searches:
• To perform a single wildcard character search, use the "?" symbol.
• To perform a multiple wildcard character search, use the "*" symbol.
The single wildcard character search looks for terms that match those with the single character replaced. For
example, to search for text or test you can use the search:
te?t
Multiple wildcard character search looks for 0 or more characters. For example, to search for test, tests or
tester, you can use the search:
test*
You can also use the wildcard character search in the middle of a term:
te*t
Note: You cannot use a "*" or "?" symbol as the first character of a search.
Boolean operators
Boolean operators allow you to combine search terms. Rollbase supports AND, +, OR, NOT and -. The operators
must be entered in capital letters as shown.
Operator Description Example
OR The OR operator is the default For example, to search for records
conjunction operator. If there is no that contain either "Human
Boolean operator between two Resources" or just "Human" use the
terms, the search uses OR. The OR query: "Human Resources"
operator links two terms and finds Human or "Human Resources"
a matching record if either of the OR Human.
terms exists in record fields or file
attachments. This is equivalent to
a union using sets. You can use the
|| symbol instead of the word OR.
AND The AND operator matches records To search for documents that
where both terms exist somewhere contain "Human Resources" and
in one or more record fields or file "Sales" use the query: "Human
attachments. This is equivalent to Resources" AND Sales
an intersection using sets. You can
use the && symbol instead of the
word AND.
+ The + required operator requires For example, to search for records
that the term after the + symbol that must contain "Human" and may
exists somewhere in a single record contain "Resources" use the query:
field or in one of its file attachments. + Human Resources
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 41
Chapter 2: Introduction to Progress Rollbase
Operator Description Example
NOT The NOT operator excludes records For example, to search for records
with fields or file attachments that that contain "Human Resources" but
contain the term after NOT. This is not "Sales" use the query: "Human
equivalent to a difference using Resources" NOT Sales
sets. You can use the ! symbol
instead of the word NOT. Note: The
NOT operator cannot be used with
just one term. For example, the
following search will return no
results: NOT Sales
- The - prohibit operator excludes To search for records that contain
records with fields or file "Human Resources" but not "Sales",
attachments that contain the term use the query: "Human
after the - symbol. Resources" - Sales
Escaping special characters
In a search query, you can escape the following characters so that the search interprets them literally instead
of as operators:
+ - && || ! ( ) { } [ ] ^ " ~ * ? : \
To escape these characters, use the backslash (\) before the character. For example, to search for (1+1):2,
use the query:
\(1\+1\)\:2
Object search
To find records of a specific object type:
1. Do one of the following:
• Click Search on page 39 and select the object type from the drop-down menu.
• Select Search from the page menu:
42 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Navigating the Rollbase environment
2. Enter search criteria in the search fields:
The Search by Distance appears only on search screens for objects that have a Location attribute. Search
results display in the object's Search Results page. You can change the default view that is used to display
search results by editing this page, selecting the Search Results List component, and selecting the desired
view in the Default List View field in the Properties box.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 43
Chapter 2: Introduction to Progress Rollbase
Metadata search
Metadata stores the definition of Rollbase applications and their components, including properties and attributes.
Metadata XML reference on page 1158 lists all metadata elements.You can use Rollbase Search to find strings
in the metadata and then sort the results by type. For example, since metadata includes the integration name,
you could search for a field integration name and sort the results to locate the formulas that use that field.
The results of a metadata search include:
• The entity type, such as application, object, or trigger.
• A link to the page to view the entity
• The related object, if applicable
• Where the text was found
• When the entity was last updated
• Who last updated the entity
To perform a metadata search:
1. Click search.
2. From the filter drop-down, select Metadata.
3. Enter a search string in the Search box.
Note: The metadata search is not case sensitive and you can use Wildcard characters in your search string
as described in Wildcard character searches on page 41.
4. Click Search.
5. You can do the following on the search results page:
• Click a heading in the result table to sort the rows.
• Click a link in the Entity column to view the entity.
44 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Navigating the Rollbase environment
The following graphic shows sample results of a search for the string google:
Language-specific search and indexing
Text indexing uses the base language, which is set on the Account Settings page and applies to all users of
the customer tenant. Users can enable other languages, but those will not be indexed. Full-text search of
languages other than the base language is not guaranteed.
If you choose to change the base language from the Account Settings page, please ask support to re-create
full-text index for your company.
The minimum length of a query for text search is one character for Asian (multibyte) languages and three
characters otherwise.
Printing and PDF generation
The Page Options menu has options for rendering the contents of the current page in a new window and for
viewing the page content in PDF format:
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 45
Chapter 2: Introduction to Progress Rollbase
46 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Navigating the Rollbase environment
Printing Screens
All editable Rollbase pages have a Print menu item in the Page Options menu that renders the current page
without the sidebar or header in a new window. Links and buttons in the window are intentionally disabled.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 47
Chapter 2: Introduction to Progress Rollbase
PDF Rendering of Record Lists
View and list pages have a Print menu item in the Page Options menu for viewing the records they contain
in PDF format.The PDF rendering displays in a new window as shown; roll your cursor in the footer to access
a toolbar for repositioning, saving, zooming, and printing.
Sample applications
Another good way to become familiar with Rollbase is to install one or more ready-made starter applications
from the Marketplace earlier known as the Application Directory.
Note: Application Directory is only available for those Rollbase Private Cloud users whose master tenant
administrator updated from a prior version to Rollbase 4.0 and did not enable Marketplace.
48 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Sample applications
Hosted Rollbase Marketplace contains only applications approved by Rollbase. The master administrator
decides which applications will be available in it. Administrators can install any application from the Marketplace
into their users' accounts with a single click. This enables them to immediately deploy critical business
applications to the right people in the organization.
Users can browse the Marketplace without being signed in. If they do not yet have a Rollbase account, they
can sign up for a free trial from an application page and that application will be installed into their tenant
automatically once it is created.
For more information about installing and updating applications from Marketplace, see Using the Progress
Rollbase Marketplace on page 692.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 49
Chapter 2: Introduction to Progress Rollbase
50 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
3
What's New in Rollbase 5.3
With latest features and enhancements to platform development capabilities, Rollbase 5.3 offers the advantage
of vastly improving the user experience of a citizen developer.
Here’s a quick overview of the enhanced features and documentation in the Rollbase 5.3
1. Enhanced Loop Section in Custom reports
The drag-n-drop user interface of the Loop Section in Custom reports empowers the citizen developers to
quickly and easily design multi-layered custom reports without the need to code. The drag-n-drop user interface
comprises predefined data rendering patterns such as Table, Bullet and Number list. You can easily configure
the loop section with any object or related object field(s) to design complex, multi-layered custom reports.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 51
Chapter 3: What's New in Rollbase 5.3
For detailed information of this feature, refer Custom Reports.
2. Record Validation on Multi-tabbed pages
Validation errors are highlighted for tabs with an error icon and is brought into focus automatically. This enables
the end users to identify which field(s) on a multi-tabbed page has error(s).
For detailed information of this feature, refer Record Validation.
3. Related Object support for Expression Fields
The expression fields now aid an automatic evaluation of the field value on any related-object field update.
This triggers the expression field update on selecting the related-object fields as configured by the admin. This
offers a better command over the expression fields.
• Apart from the automatic evaluation, an admin can also force-update the expression field value from the
field definition page.
• The expression fields are now in feature parity with formula fields. Hence, they can also be converted into
formula fields and vice-versa.
52 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
• Expression fields can also be used in the View Filters and Color Code View.
For detailed information of this feature, refer Expression Field.
4. SFTP Support for Batch jobs
With the new Secure FTP support, you can highly secure the file transfers by configuring batch jobs. While
defining, you can also configure the batch jobs by providing the SFTP server location with credentials. Rollbase
currently supports the following types of batch jobs with SFTP configuration:
• FTP Data Snapshot
• Scheduled FTP Import
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 53
Chapter 3: What's New in Rollbase 5.3
5. Introducing new APIs for Date and Date/Time Fields
The newly introduced APIs can get the Date and Date/Time field values in specific (ISO or User) formats. This
provides better administration of the returned values.
The APIs targeted to enhance the Date and; Date/Time fields are listed below based on homogeneity.
1. Support for ISO Date and Date/Time formats in Client-side AJAX API using useISODateFormat parameter
in options.
• rbf_getFields
• rbf_getRelatedFields2
• rbf_getPage
• rbf_getPage2
• rbf_getViewPage
• rbf_selectQuery2
• rbf_selectValue
• rbf_selectQuery
2. Support the ISO Date and Date/Time formats in the response of REST API requests with Shared Properties
UseISODateFormatInRESTJSON and UseISODateFormatInRESTXMLQuery
• getDataObj
• getDataField
• getPage
54 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
• getRecord
• selectQuery
• selectValue
3. The following are the utility methods under the Client-side AJAX API for Date and Date/Time format
interconversion between User format and ISO format.
• rbf_getDateInUserFormatFromISO
• rbf_getDateInISOFromUserFormat
4. The following are the utility methods under the Server-side API for Date and Date/Time format interconversion
between User format and ISO format.
• rbv_api.getDateInUserFormatFromISO
• rbv_api.getDateInISOFromUserFormat
5. The following are the utility methods under the Server-side API for Date and Date/Time object interconversion
between JavaScript native object and Java Date objects.
• rbv_api.toJSDate
• rbv_api_toJava
Note: Added other methods like rbv_api_toJS and rbv_api_getClassName which are commonly applicable
to all the APIs but not specific to Date and Date/Time for native JavaScript and debugging respectively.
1. Support for moment.js library included in the all the pages from Client-Side APIs can be invoked
2. Support for useLegacyDateFormat in REST APIs has been discontinued.
Miscellaneous
Rollbase 5.3 includes the following minor enhancements in this release:
• New Shared Property SessionInfoLogEnabled (Default value: off) to log session creation and session
deletion to the servlet context log.
• New Shared Property BootStrapVersion (Default value: 4.1.1) to act as a fallback value if no value is
specified as per application level.
• New Shared Property ShowAttachButtonForGridControl (Default value: On) to toggle the visibility of the
Attach button in a grid control.
• Optimized data translation cache and number of queries around RB_TRANSLATION for improved
performance
• Optimized relationship cardinality checks during app install for improved performance
• Calculation of storage size per customer no longer includes log or backup directory size
• New field maxSystemBackups added to the customer object definition. This value overrides instance level
value for MaxSystemBackup.
• Upgraded Bootstrap version 4.1.1 and latest Kendo versions.
• Added support for filter options to Text Area fields.
• Fixed sort clause to work with OESO objects.
• Composite primary key introduced on RB_RELATIONSHIP and RB_TRANSLATION table.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 55
Chapter 3: What's New in Rollbase 5.3
• Server API is now an admin role.
For details, see the following topics:
• What's New in RollBase 5.2
• What's New in Rollbase 5.1
• What's New in Rollbase 5.0
• Upgrading Private Cloud to Version 5.x
• Upgrading Private Cloud to Version 4.X
What's New in RollBase 5.2
While the set of new and enhanced features are designed to keep you attuned to Rollbase 5.2, the cool UI
themes and navigational options aim at keeping you engaged with simpler and intuitive functionality. You can
also look forward for an improved meaning while performing certain administrative tasks that are essential for
your business.
1. Creating a new role from the existing roles
This new feature enables you to quickly create a new role by selecting multiple existing roles. When a new role
is created in this way, it offers the benefit of acting as a super-set of the existing roles. This enables the new
role to perform multiple functions because the new role inherits pages and a union of permissions of from the
selected roles. The admin creating this role can do this quickly without the hassle of losing time in detailed
consideration of the required attributes.
For detailed information of this feature, refer Creating and editing user roles .
2. PDF Annotator
As the name indicates, the PDF Annotator equips you with the ability to annotate a PDF file with greater flexibility
in terms of performing the following vital operations from a Grid view page, Record details page, and Record
edit pages:
56 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
What's New in RollBase 5.2
• Inserting a new page at the end of the file
• Appending pages or another PDF file at the end of the current file
• Moving a selected page to the desired location in the file by changing the page number
• Removing selected page(s)
• Quickly navigating between previous /next pages
• Highlighting text
• Dragging or removing an added shape
• Adding text and format it (viz., bold, italic, font size, font family, font color)
• Adding your signature to the PDF and relocating it using the drag tool
• Deleting the page corresponding to selected thumbnail
• Saving the file
This feature is currently enabled only through a shared property IsPDFAnnotationEnabled=true, which
is OFF by default.
3. Creating users without welcome emails
This enhancement empowers the Rollbase administrator to create users with specific roles and perform the
required configuration for newly created users. An admin can test user configurations before sending the
welcome email to the actual user. Send welcome email is available as a checkbox in Create/Edit user pages
to disable/enable welcome email for the user account. Also, the mass-update option is available for the admin
role, should they have the need to activate users and send the welcome email in bulk.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 57
Chapter 3: What's New in Rollbase 5.3
For more information, see Viewing and editing an object definition.
4. Grid Control enhancements
Grid control now offers added capabilities such as attaching existing records, option to choose to display field
level help, and an edit icon for the added records.
• Attaching records: A user can now attach a record from the Grid control on record edit and create pages.
The attached record can also be updated during the attach flow.
See Revised Grid control and Using a Grid control.
• Field-level help/tool tip: This is a new field level help setting. When enabled, the field-level help tool tips
appear in both tabular and responsive grid controls. If this setting is disabled, the UI is rendered without the
tool tips.
Note: This setting will be enabled in the grid control configuration only if it is enabled in the app settings.
For detailed steps, see Configuring a grid control.
• Grid data: The Actions column now has an edit icon, which is always visible for a record. A similar change
has been made for the Card view page as well.
58 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
What's New in RollBase 5.2
Delightful Apps - UI Enhancements
Rollbase continuously strives for user interface improvements to enrich the end user experience. In this release,
significant changes have been made to the Rollbase user interface. These changes are focused around better
use of available real state, UI consistency, logical flow and grouping of links / buttons / menu and so on from
a usability perspective.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 59
Chapter 3: What's New in Rollbase 5.3
• App Selector: To achieve a greater intuitiveness, the App selector is now positioned more appropriately
next to the Application name similar to the Traditional Blueprint for consistency.
• Page Title Menu: A new icon for the Page Title menu launcher has been added for improved consistency.
Here's the screenshot:
• Overflow Menu: The Record view page overflow menu icons and style has been made consistent in line
with other menu options across the Rollbase platform.
• LDF Tree Action: The LDF tree list is now available along with the Edit and Delete action buttons instead
of in a menu. Each LDF record now has an Edit icon to edit an LDF record. To delete an LDF record, the
user must select the row by clicking on the record. When performing this action, the "Delete" button in the
toolbar is enabled. To delete the LDF records, the user must click the delete button and confirm the delete
action.
60 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
What's New in RollBase 5.2
• Record View Page: The Record View page has been updated in the Modern Blueprint for a greater appeal.
A button toolbar is now available to update the record flag status. When an object is enabled for flagging,
the user can update the flag status from the Record view page.
As shown below, the Record View page design in mobile devices has been updated for improved usability.
• Card Sort Dialog: The Card sorting dialog now contains fields from both the cards and the selected view.
This helps the users to apply sorting for fields that are not part of card to quickly sort the cards in the mobile
devices.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 61
Chapter 3: What's New in Rollbase 5.3
• Report Link: The Report link icon has been updated to make it appear consistent across the Rollbase
pages.
• Page Tool Menu: The Page Title menu has been enhanced with an option to display the relevant runtime
context of the Tab. The “Object Definition” for the admin roles are moved and grouped under the Page Tool
menu. The “Tab Definition” options for app developer users are moved and grouped under the Page Title
menu. The Page tool menu is replaced with a simple button instead of icons.
For more information, see Viewing and editing and Object Definition and The Tab Options menu.
• App Preview: Live Preview has been renamed as App Preview and this functionality is now available as
a menu item only under the Application Switcher. App Preview popup option too has been rearranged and
logically grouped.
For more information, see Using the Application Switcher and App Preview on page 405.
62 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
What's New in Rollbase 5.1
• Font Color configuration for Charts: A new property is now available to configure the base font color of
the Fusion charts. This value must be chosen based on the chart background such that the text is clearly
visible on the rendered chart.
Bootstrap Version Configuration
• Application Settings: A new property has been added to the application settings to specify the bootstrap
version that needs to be used at newui runtime for an application. Administrators can change this setting
from the app edit page. All the supported versions are available for selection.
• If v3.3.7 is selected, the corresponding Bootstrap v3.3.7 CSS and JS files are loaded in the newui.
• If v4.x is selected, the corresponding Bootstrap v4.x CSS and JS files are loaded in the newui.
• If an app is imported from a previous version of Rollbase release, by default, the v4.x option is selected
in the app after the import is completed.
• Portal Settings: A new property has been added to the portal settings to specify the Bootstrap version to
be used at newui runtime for a portal page. Administrators can change this setting from the portal edit page.
The supported bootstrap versions for portal pages are:
• If an existing portal had Use Boostrap v3 checked, then to preserve that option, the newly introduced
property will be set to v3.3.7. If Use Bootstrap v3 is unchecked, the newly introduced drop down will
have v2.3.1 selected.
• While creating a new portal, by default v2.3.1 will be selected for the Bootstrap Version property.
• This property is honored in the app import/export and CDN scenarios.
What's New in Rollbase 5.1
Rollbase announces exciting new features and enhancements with its new release, that aim at delivering value
and enriching the user journey. These new features propel the overall experience of the system functionality
to promote greater value-add and ease of use. This section summarizes the new Rollbase 5.1 features with
pointers to detailed information.
1. Support for Multiple Authentication
The new Rollbase 5.1, enables a single Tenant administrator to support more than one identity management
system for a given application or solution and provide access to different users on that application. With this
feature, your application users can now be from different identity provider(s) and have a seamless Single
Sign-On experience.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 63
Chapter 3: What's New in Rollbase 5.3
Support for multiple authentication is applicable per tenant authentication only. In case of global authentication,
the settings configured in the Control Panel are considered for authentication.
Rollbase authenticates all roles with the default authentication profile. The default authentication profile is the
existing authentication for any specific customer prior to Rollbase 5.1. If any of the UI or API authentication for
a specific role is selected as NONE then, the users under that role will not be able to login with that specific
authentication profile. Kerberos and Custom authentication profiles are available only if the master tenant
configures these.
For detailed information of this feature, refer Supported Methods to Authenticate Users and Control Panel.
2. Creating Multi-layered Tabular Reports
The newly enhanced Tabular Reports help you to easily configure multi-layered reports and export the multi-levels
as a flat list without the hassle of duplicating records and data. The data export layers limit is controlled by the
shared property TabularReportLayeringLimit and is applicable for export to XLS, XLSX and CSV formats.
Each level is limited to the maximum number of records as specified by the shared property MaxExportRows.
Also, providing export options to define export format as shown below.
Refer Creating Tabular Reports to understand more about this functionality.
64 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
What's New in Rollbase 5.1
3. Enhanced Custom Reports
Enhancements to the existing Custom Reports functionality enables Rollbase engineers to design reports
across multiple objects with greater options to choose for different sections within a report. This provides you
with greater control and flexibility via the Point-and-Click & Drag-and-Drop approaches. Custom reports can
also be record specific to generate report in the context of a record.
For detailed information about applying this functionality, refer An Overview to Custom Reports.
4. New Built-in Parsers for Aspose PDF/Word
Rollbase now includes a built-in parser as an alternative to Aspose PDF and DOCX. The built-in parser will
remain as the default choice. Rollbase continues to support Aspose PDF/Word with newly introduced configurable
shared properties and customer preference.
However, support has been deprecated for DOC and RTF files in document templates and reports. Already
existing ones will work if you have Aspose parsers enabled but the new RTF and DOC templates cannot be
uploaded.
For specific information on how to enable or configure Apache POI or Aspose, refer Working with Customer
Records, and the Add/Remove Features under Shared Properties .
Enhancements
• Data Maintenance Job: The purpose of this job is to enable the Master admin to fix the data integrity issues
pertaining to relationship and data records, and cleanup orphan relationship entries for customer tenants.
For more information refer Maintaining Customer Data.
Note: As a best practice, run this utility immediately after upgrading to Rollbase v 5.1
• Password URL Expiration: A new property - NewUserPasswordActivationLinkExpiry has been added
to the shared property at Master level and authentication profile at Tenant level for the new user activation
link to expire. Refer User authentication and password management on page 680 for more information.
• A new field option, Overwrite existing values has been added to the Mass Update properties to overwrite
the existing values of a look-up field.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 65
Chapter 3: What's New in Rollbase 5.3
What's New in Rollbase 5.0
This topic describes the list of new features and enhancements as part of Rollbase 5.0
With a set of new and improved enterprise business features, Rollbase strives to continually delight its customers.
The Rollbase 5.0 release revolves around empowering users with high availability, auto scalability, greater
effectiveness and simpler, more intuitive UI. All of these enhancements and features work together to promote
greater efficiency.
Visual Workflow Designer
The Visual Workflow Designer provides a powerful drag-and-drop interface that enables you to visually build
your workflow processes to achieve better work outcomes. The new intuitive interface adds greater clarity
around how you want to map your process steps using statuses, actions and triggers through visual
representation like a flowchart and allows you to define your workflow processes with ease.
The new Visual Workflow Designer is fully compatible with workflows from prior Rollbase releases. So, you
can continue to manage all your existing workflows as usual and design them in the new Visual Workflow
designer.
See Working with the Workflow Designer for more information.
Cluster Manager for High Availability and Auto Scalability
With its Active-Active High-Availability, Rollbase 5.0 now offers your business applications maximum uptime
and better fault tolerance in a cost-effective manner. All Rollbase components can now be configured for high
availability to manage your server usage on AWS in a more efficient and cost-effective manner.
Rollbase 5.0 also enables your business applications to respond to varying load requirements by configuring
your own rules and policies through the use of tools like Elastic Load Balancing and Auto Scaling. You can
automate the infrastructure to ensure that risks related to potential loss of readership, sales, or the attrition of
customers are mitigated with servers that can be spun up as network traffic increases and scaled down when
traffic decreases.
66 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
What's New in Rollbase 5.0
See Configuring High Availability for more information.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 67
Chapter 3: What's New in Rollbase 5.3
• Rollbase System Console
Rollbase offers an enhanced System Console dashboard. From there, you can easily view, configure and
manage all the Rollbase system components, servers, databases, customer load, shared properties, control
panel and monitoring jobs. This does away with the hassle of working in the backend to perform tasks such
as manual configuration of shared properties and waiting for system restart. With the System Console
dashboard, tedious tasks like system configuration and load balancing become a swift and easy experience.
See System Tab Interface for more information.
• Dynamic Request Routing with Nginx
With bigger sites, you will need multiple Node instances to scale quickly and manage greater volumes of
traffic. To effectively handle your traffic, Rollbase allows you to configure Nginx. Nginx decides where to
route a request with Active/Active clustering, supporting greater throughput without a single point of failure
and maintains isolation of tenant cache. Nginx follows an asynchronous event-driven model for handling
requests.
When configuring Nginx in the private cloud, update the default Nginx pages such as index.html, 404.html,
50x.html (for all 500 series error codes) and favicon. Rollbase ships these pages under the …/nginx/html
folder.
See Configuring Nginx for more information.
• Distributed Cache to Support Seamless Horizontal Scalability & Resiliency
With distributed cache, Rollbase has seamless horizontal scalability and resiliency and to serve one customer
from multiple nodes and enables in-memory access to frequently used data as it pools resources from
several servers. This provides the benefit of all nodes sharing the load of responding to requests while
limiting the interruption to routine Rollbase operations during optimization and maintenance activities. In
turn, this helps increase performance with minimal disruption.
• Improved Job Resiliency
Rollbase supports job resiliency so that all background operations for your business applications are executed
seamlessly regardless of node failures or other external error conditions. Rollbase supports the below job
pools for resiliency:
• Delayed Trigger jobs
• Batch jobs
• Import jobs
• Large jobs
• Mail jobs
68 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
What's New in Rollbase 5.0
See Components (Running Jobs section) for more information.
• Highly Available Search
Large-scale, online production systems need to be highly available without downtime despite any issues
that may be encountered. Rollbase ensures that the search re-indexing jobs of such systems are not lost,
or processed twice and are not prone to corruption in the event of failure or problematic issues.
Enhanced Auto-number
The Auto-number field behavior has been enhanced to provide consistent user experience across UI and API
for better ease of use. We have also enhanced the Auto-number functionality to be better managed for change
in the auto number sequence, concurrency and bulk operation through API or Import Jobs.
See Auto-number Functional Changes for more information.
Client-side REST API Invocation
This feature introduces a powerful client side AJAX API rbf_sendHttpRequest in the Rollbase platform to
enhance customization capability of Rollbase application. This AJAX API enables developers to invoke REST
APIs from Rollbase Pages and Portal pages using custom script components.
UI Enhancements
With Rollbase 5.0, we focused on improving usability and the end user experience through new app
configurations that enhance different UI elements.
• Configuring UI Blueprint for Desktop and Mobile: Rollbase 5.0 enables you to offer distinct experiences
to users based on the type of device used to access the application. This is done by managing application
level configuration to define different Blueprints for mobile and desktop.
• Click to Call: Rollbase now provides the Click to Call feature for Rollbase applications on your desktop
and mobile devices. Any phone number will automatically appear as a clickable link enabling users to quick
dial the number from the UI.
• Enhanced Configurable Positioning of Notifications: You can now better configure Rollbase notification
messages to appear based on the context of your application. With Rollbase 5.0 notification messages can
be set to display at the center, top corner or bottom corner.
• Mobile-friendly Grid Control: The new Rollbase grid control provides visual consistency between layouts.
It also enables you to configure as per application requirements, which improves the experience for mobile
users. The new responsive grid control provides larger clickable areas that enable you to collapse or expand
each row inside individually.
CDN Support
To augment the transport network and improve the performance and scalability of various deployments, Rollbase
provides Content Delivery Network (CDN) support. CDN support provides the following benefits:
• Improved client-side performance and faster page loading by caching static files
• Increased server -side scalability by serving static files from Tomcat/Nginx
See CDN Support for more information.
HTTP/FTP Request Retry
Rollbase provides support for applications to handle transient failures by retrying failed operations. This can
improve the stability of the application. To achieve this, Rollbase has added retry parameters for HTTP trigger
types and FTP batch jobs by enabling and configuring status codes, number of retries and retry interval
parameters.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 69
Chapter 3: What's New in Rollbase 5.3
See HTTP Triggers for more information.
Improved Client-side Performance
Rollbase 5.0 delivers key performance enhancements to UI, business layer and data layer interaction, which
improves the chart rendering performance through better use of cache and limiting unnecessary database
queries. This will also improve the performance of ListView, lookup fields and grid controls.
Upgrading Private Cloud to Version 5.x
To migrate data from previous releases of Rollbase Private Cloud to the latest release, you need to run scripts
to update your database sequentially. For example, to update from version 4.3 to version 5.0, you first need
to run the script to upgrade to 4.4, 4.5 and then to 5.0. Check the PDF documentation included with each
version to determine whether to change code in formulas or external systems that access Rollbase data through
the SOAP or REST APIs.
The following steps describe how to upgrade Rollbase Private Cloud from a prior release to the latest release:
1. Make a copy of your existing Rollbase config, storage and rollbase\personalize folders.
2. Stop PAS or Tomcat.
3. If you have any custom files, such as FusionCharts, in the webapps folder of your Tomcat instance, copy
these to a folder for later use.
4. Stop the database.
5. If you installed using the Rollbase installer, run uninstall. You can launch it from the Rollbase\uninstall
folder. If you were using the OpenEdge database, uninstall will not delete the OpenEdge working directory,
which contains your data.
6. If you used your own Tomcat instance, delete the following folders from the webapps folder: master,
router, prod1, search, storage, rest, webapi, rss, workflow
7. Install Rollbase 5.X using the installer or zip files:
a. If you use the installer, consult the configuration files you saved for host, database, and email configuration
values. If you were using the OpenEdge Database, point the installer at the working directory that contains
your data.
b. If you use the zip files to install, configure Rollbase as follows:
a. From the config folder, open the node-config.json.
b. Edit the node-config.json file with the shared properties information such as email information:
host name and port number, and the email address and password for the main administrative user.
c. In the node-config.json, update the databases related information. See Editing the
node-config.json file on page 770.
Note: In Rollbase 5.0, in the config folder, the following files will be available as per the new
structure: cluster-config.xml,master-cluster-config.xml, node-config.json,
prod-cluster-config.xml, jaas.conf and meta-psc-rollbase-idp-test .
8. Copy all the files from the backed up config folder to <ROLLBASE_HOME>/config folder. Do not copy paste
the entire config folder.
70 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Upgrading Private Cloud to Version 5.x
9. Copy the storage folder to the new storage server node.
10. If you saved any custom files from the webapps folder as described in step 3, copy them into the new
installation. For example, copy the personalize folder.
11. When upgrading from a previous version to 5.x, remove the following JAR files:
• encoder-1.2.jar
• hazelcast-all-3.7.jar
• pdfbox-2.0.2.jar
• cos.jar
• httpclient-4.5.jar
• httpmime-4.3.jar
12. In the Rollbase\sql folder, find the appropriate script(s) to update your database. Note: If you installed
the Progress Application Server for Rollbase, these files are in the Pas_Instance\Rollbase\sql folder.
If you are upgrading from a version other than the previous release, you will need to use multiple scripts,
starting with the next version higher than your existing installation and continuing until you reach the current
script.
13. Open the sql script(s), and do the following:
a. Uncomment the section for your database type.
b. Verify that the sections for other database types are commented out.
c. Add the following commit statement to the end of the file: COMMIT WORK
14. If you are using a database other than the OpenEdge instance included with the installer, start your database.
If you are using the OpenEdge database that comes with the installer, it should be running already.
15. Start the Progress Application Server or Tomcat.
After you have upgraded your Private Cloud installation as described in, perform the following steps to
re-index customer tenants:
Re-indexing Customer Tenants
Follow these steps to re-index customer tenants:
1. Log into the master server as an administrator.
2. Navigate to the System Console.
3. From the System tab menu, select Reindex.
4. On the Reindex page, select the appropriate scope:
• Master zone
• All customer tenants
• Selected customer tenants
You can select the master zone and all or selected tenants. Progress strongly recommends re-indexing the
master zone and all customers, but re-indexing customer tenants one or a few at a time can minimize
performance impact.
Confirm that indexing has occurred by doing the following:
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 71
Chapter 3: What's New in Rollbase 5.3
1. Navigate to Setup Home.
2. In the Administration section, click Global Text Search.
3. Click View Search Logs.
Upgrading Private Cloud to Version 4.X
To migrate data from previous releases of Rollbase Private Cloud to the latest release, you need to run scripts
to update your database sequentially. For example, to update to version 4.4 from 3.2, you first need to run the
script to upgrade to 4.0, then 4.1, then 4.2, then 4.3, and finally, 4.4. Check the PDF documentation included
with each version to determine whether to change code in formulas or external systems that access Rollbase
data through the SOAP or REST APIs.
Note: When upgrading to 4.4, be sure to remove the outdated third-party JAR files that were replaced. See
the description in Step 9.
Due to a change in search functionality for version 3.0.5, Private Cloud users upgrading from a release prior
to 3.0.5 must re-index all tenants. Re-indexing must be performed on the master server by an administrative
user.
The following steps describe how to upgrade Rollbase Private Cloud from a prior release to the latest release:
1. Make a copy of your existing Rollbase config and storage folder.
2. Stop PAS or Tomcat.
3. If you have any custom files, such as FusionCharts, in the webapps folder of your Tomcat instance, copy
these to a folder for later use.
4. Stop the database.
5. If you installed using the Rollbase installer, run uninstall. You can launch it from the Rollbase\uninstall
folder. If you were using the OpenEdge database, uninstall will not delete the OpenEdge working directory,
which contains your data.
6. If you used your own Tomcat instance, delete the following folders from the webapps folder: master,
router, prod1, search, storage, rest, webapi, rss, workflow
7. Install Rollbase 4.X using the installer or zip files:
a. If you use the installer, consult the configuration files you saved for host, database, and email configuration
values. If you were using the OpenEdge Database, point the installer at the working directory that contains
your data.
b. If you use the zip files to install, configure Rollbase as follows:
a. From the config folder, open the shared.properties and databases.xml files.
b. Use the files you copied as references and make any necessary updates. At a minimum, in the
shared.properties file, enter the email information: host name and port number, and the email
address and password for the main administrative user.
8. If you saved any custom files from the webapps folder as described in step 3, copy them into the new
installation.
9. When upgrading from a previous version to 4.4, remove the following JAR files:
72 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Upgrading Private Cloud to Version 4.X
• aws-java-sdk-core-1.9.6.jar
• aws-java-sdk-kms-1.9.6.jar
• aws-java-sdk-s3-1.9.6.jar
• fontbox-2.0.0-RC3.jar
• httpclient-4.5.jar
• httpmime-4.3.jar
• jackson-annotations-2.3.0.jar
• jackson-core-2.3.2.jar
• jackson-databind-2.3.2.jar
• oshi-core-1.5.2.jar
• pdfbox-2.0.0-RC3.jar
• ss_css2.jar
10. In the Rollbase\sql folder, find the appropriate script(s) to update your database. Note: If you installed
the Progress Application Server for Rollbase, these files are in the Pas_Instance\Rollbase\sql folder.
If you are upgrading from a version other than the previous release, you will need to use multiple scripts,
starting with the next version higher than your existing installation and continuing until you reach the current
script.
11. Open the sql script(s), and do the following:
a. Uncomment the section for your database type.
b. Verify that the sections for other database types are commented out.
c. Add the following commit statement to the end of the file: COMMIT WORK
12. If you are using a database other than the OpenEdge instance included with the installer, start your database.
If you are using the OpenEdge database that comes with the installer, it should be running already.
13. Start the Progress Application Server or Tomcat.
After you have upgraded your Private Cloud installation as described in, perform the following steps to
re-index customer tenants:
Re-indexing Customer Tenants
Follow these steps to re-index customer tenants:
1. Log into the master server as an administrator.
2. Navigate to the System Console.
3. From the System tab menu, select Reindex.
4. On the Reindex page, select the appropriate scope:
• Master zone
• All customer tenants
• Selected customer tenants
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 73
Chapter 3: What's New in Rollbase 5.3
You can select the master zone and all or selected tenants. Progress strongly recommends re-indexing the
master zone and all customers, but re-indexing customer tenants one or a few at a time can minimize
performance impact.
Confirm that indexing has occurred by doing the following:
1. Navigate to Setup Home.
2. In the Administration section, click Global Text Search.
3. Click View Search Logs.
74 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
4
Designing a Rollbase application
The core components of Progress Rollbase applications are objects, tabs, and portals. Each of these components
consists of sets of configurable sub-components such as fields, pages, and menus. You define these application
components to form a fully functional SaaS solution.
As shown in the following graphic, the basic steps involved in creating a Rollbase application include:
1. Think about how your application will be exposed or distributed to users, through the public cloud, private
cloud, as an application, and/or through a portal.
2. Create the application foundation, including the objects and relationships that define the data model.
3. Add application logic to derive business value from the data.
4. Define and customize the user interface.
5. Define permissions and security.
6. Test and deploy.
The following image illustrates the typical process for developing Rollbase applications:
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 75
Chapter 4: Designing a Rollbase application
Rollbase offers a flexible and mature environment, suitable for the most demanding of applications.
As with any application development, these steps do not necessarily follow in order and are iterative. The
following topics discuss each step in more detail:
For details, see the following topics:
• Application foundation
• Business logic and customizing the user experience
• Setting up accounts for testing
• Distribution options
Application foundation
To create a Rollbase Web application foundation, you define application components. Component definitions
consist of properties and attributes, and for some components, subcomponents (child components). Rollbase
stores component definitions as metadata. With the appropriate permissions, external applications can access
application metadata using SOAP or REST. See Using SOAP or REST to integrate with Rollbase on page 637
for more information.
This section introduces and describes components that lay the foundation for a Rollbase application:
• Applications: A container for a logical grouping of objects, exposed to users through menus, and, optionally,
portals.
• Objects: The core component of Rollbase applications, each object defines the structure for data of a
particular type. Objects and relationships between objects create the application data model. Rollbase stores
object data as records.
• Fields: The core component of objects, each field defines characteristics such as data type for a discrete
piece of data. Users enter record data into fields, such as Name and Address.
76 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Application foundation
• Relationships: Link objects together. For example, a shipment might be related to the individual ordered
items that comprise that shipment.
• Pages, and menus: Pages make up the user interface of a Rollbase application. When you create an object,
Rollbase creates a set of pages for creating, viewing, and editing records. Menus are the navigation controls
associated with pages. Rollbase creates pages and menus for you, but you have the option to customize
them and to create others to enhance the experience of your end users.
• Portals: Within an application, a way to expose all or subsets of Rollbase application functionality to end
users and other external entities. Instead of logging into Rollbase to access application functionality, users
log into the portal, which can be integrated into your website. You create the portal pages and control the
user experience.
• Calendar: A built-in application that contains task and event records that you can use to coordinate work
for yourself and/or for a group of Rollbase users.
Watch a short video to see how quickly you can create an application with objects and relationships: The Quick
Create Wizard. The topics in this section provide more details on objects.
Object definition overview
Object definitions are containers for fields. They have attributes and properties that specify how the individual
records are structured, how they will behave, and how they can be accessed. Object definitions also contain
the following child component definitions: fields, relationships, views, templates, pages, reports, charts, gauges,
and triggers.
Object definitions specify read/write permissions per role and per user. They also have a complete administrative
audit trail, allowing you to see the who, what, and when of any change that occurred to an object definition, its
components, or the associated records. The following screen shows an example object definition for Furniture
records. The ribbon of Fields, Relationships, and other components contains links to navigate to the section
of the object definition where those child components are defined.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 77
Chapter 4: Designing a Rollbase application
You can create object definitions using the Quick Create wizard, from scratch, by importing from spreadsheets
or other applications, or by linking to data stored in other applications. An import usually brings in records, and
if those records do not map to existing object definitions, new object definitions can be created as a side effect.
Those procedures are described in:
• Getting Started with the Quick Create Wizard
• Creating and Managing Objects, Fields, and Relationships
• Importing to Create a New Object - describes how to create an object from a spreadsheet.
• Linking a Rollbase Object to OpenEdge
• Using DataDirect Cloud to Access External Data
• Creating Rollbase Applications from Microsoft Access
• Creating Rollbase Applications from Salesforce Applications
• Using External Tables as Rollbase Objects
Object definitions can be shared among applications. Records for a particular object in a tenant will be available
in any application that includes that object. When you publish an application, you can choose to add sample
records as seed records for the users who will install the application.
Once an object definition exists, in addition to editing and adding fields and properties, you can do the following:
• Clone an object — Create a new object definition with a new name and copy all components, fields, triggers,
etc. to the new object.
• Create and run triggers — Select one or more triggers to run on all object records (for data maintenance,
etc.) See Trigger overview on page 218 for more information.
78 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Application foundation
• Define conditional formulas — Create formulas to enable/disable edit and delete functionality for object
records.
Object attributes
Object attributes add behavior and fields to an object. For example:
• Objects with Task and/or Event attributes appear in the Rollbase calendar.
• Objects with the Document attribute can store a file attachment. The file's contents are indexed in the full
text search engine.
• Objects with the Workflow attribute have fields for managing workflow processes, statuses, and actions,
allowing you to model many kinds of business processes.
• Objects with the Location attribute have fields to capture addresses.
• Objects with the Contact attribute have fields to capture phone numbers and e-mail addresses.
During object creation, you have the option to select which attributes to include. These are divided into two
categories: Attribute and Advanced Attribute. If you use the Quick Create wizard, you can add attributes,
but not advanced attributes. Once an object is created, you can add any type of attribute to it.
When you add an attribute during object creation or later, Rollbase adds a group of fields to that object. While
you cannot delete these fields, except for the integration name property, you can modify all other properties.
These new fields are added to the object view, create, and edit pages in a new section. When you remove an
attribute from an object, Rollbase deletes these fields as a group.
Attributes
You can add the following attributes to an object definition:
• Contact — Adds fields to store contact information for people or organizations. You can send contact
records by email and export them in the standard vCard format. The following fields are added when this
attribute is enabled: First Name, Middle Name, Last Name, Job Title, Phone, Mobile Phone, Fax, Email
Address, and Contact Owner.
• Location — Adds fields to store information about people, places, or organizations with associated location
and street address information. The following fields are added when this attribute is enabled: Street Address
1, Street Address 2, City, State/Province, ZIP/Postal Code, and Country. Using the Location attribute
allows you to add a Google Map component to view pages, as described in Google Maps on page 635.
• Event — Adds fields to schedule activities or meetings that have an associated start time, duration and
group of participants. You can display, create, and manage Event records in the Rollbase calendar and
export them in the standard iCalendar format. The following fields are added when this attribute is enabled:
Event Subject, Start Date/Time, Duration, All Day, Private, Description, Location, Assigned To and
Pop-up Reminder.
• Task — Adds fields to track deadlines, follow-ups, or to-dos that have a due date and one or more associated
assigned users. You can display, create, and manage Task records in the Rollbase calendar and export
them in the standard iCalendar format. The following fields are added when this attributed is enabled: Task
Subject, Due Date, Priority, Private, Description, and Assigned To.
• Document — Adds a field for file attachments and a description. Rollbase indexes attached files in standard
Word, Excel, PDF, or plain text formats for full text search. The following fields are added when this attributed
is enabled: Document File and Description.
• Organization — Adds lookup fields for associating records with organizational Location, Department, and
Function for use with location/department/function (LDF) permissions. See Location/department/function
permissions on page 669 for more information.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 79
Chapter 4: Designing a Rollbase application
Advanced attributes
You can add the following advanced attributes to an object definition:
• Workflow — Objects with this attribute can be routed through an automated or manual workflow process
defined by a set of workflow statuses and actions. The following fields are added when this attributed is
enabled: Workflow Process, Workflow Status, and Workflow Actions (list of available actions). See
Workflow overview on page 256 for more details.
• Portal User — Objects with this attribute represent registered users of one or more portals. The Portal
User fields can be used to require portal authentication and enable the creation of rich interactive portals
that expose specific capabilities of your Rollbase applications to external users. The following fields are
added when this attributed is enabled: Login Name, Password, and Is Active. See Portal security on page
540 for more details.
• Approval — Objects with this attribute are subject to an approval process. See Approvals on page 273 for
more details.
• Survey — Objects with this attribute enable a Questions Library, allowing you to create any number of
questions that can then be attached to any record to form a questionnaire. You can rank each question's
answer to assign an overall score to survey responses. See Surveys and quizzes on page 352.
• Survey Taker— Objects with the this attribute contain fields to store responses to surveys.
• Queue — Objects with this attribute can be marked to form a queue. Users can pick up records from queue
for further processing. See Record queues on page 276.
• Multi-Currency — Objects with this attribute include support for converting money amounts to and from
different currencies. See Multi-currency support on page 349
• Lockable — Objects with this attribute support locking of records Locked records cannot be edited or deleted
unless they are unlocked by trigger or API.
Relationships
Object relationships are similar to primary and foreign keys in a database. The type of relationships specifies
cardinality (how many records of one object type can be related to another):
When you create a relationship between objects, Rollbase automatically creates a lookup field in each object
that provides access to related records. Rollbase also automatically creates a view for related objects that is
added to the appropriate pages for both objects. End users will need to view and, in some cases, create and
edit related records. Depending on the cardinality of the relationship and the permissions granted, the lookup
field gives end-users the ability to view, attach, create, and remove related records.
80 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Business logic and customizing the user experience
Business logic and customizing the user experience
Masses of data can be overwhelming and difficult to manage. Applications that meet real user needs will likely
contain logic that transforms raw data into accessible information and supports business processes. Rollbase
offers a variety of built-in mechanisms that simplify the addition of business logic. These include templates,
formulas, workflows, and triggers. Since each application is unique, this documentation describes the available
features and provides examples. Progress recommends that you acquaint yourself with Rollbase capabilities
and the examples and then apply the principles to your use case.
See Adding business logic on page 183 for detailed descriptions of templates, formulas, triggers, and workflows.
Watch a short video that demonstrates basic customization: An overview of application customization.
The end-user experience is shaped both by business logic and by presentation. When you create application
objects, Rollbase creates a basic interface for creating, updating, and deleting records. You can edit these
pages to customize what they contain and their look and feel. The topics in this section provide an overview
of Rollbase user interface components. See Customizing the user experience on page 361 for more details.
Rollbase user interface components
The following table introduces the hierarchy of Rollbase user interface components:
Component Description
Application or Portal An application or portal is the topmost container for
Rollbase pages. Rollbase applications are only
available to registered users. Portals are public
websites that can access Rollbase data.
Page A page represents a single user interface page within
a Rollbase application or portal. Pages can be
formatted in one to four columns. Your Rollbase
application can have multiple versions of each page.
Users and roles can be assigned to particular versions.
You can also control the user interface based on user
and role. For more details, see Security and access
control on page 643.
Section A section is a container within a page with an optional
title and border. Sections can be organized into one
to four-column layouts.
Page tabs Page tabs are an optional part of a view page that you
can enable to organize multiple sections and reduce
vertical scrolling. See Page tabs on page 378 for details.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 81
Chapter 4: Designing a Rollbase application
Component Description
Cell A cell is a container within a section that holds a single
component. The component represents data being
displayed or a control used for editing or interacting
with data, such as a list view, grid control, or object
field.
Field A field is the lowest level user interface element on a
page, wrapped in a cell to render its contents.
The following diagram illustrates the container hierarchy of Rollbase user interface components:
Application page types
The default application pages created by Rollbase provide an interface for users to view, create, update, and
delete records. You can modify and clone these default application pages. You can create portal pages and
generic pages. You control the visibility of pages by assigning permissions by role and/or by user. End users
navigate through application pages using menus. See Application tabs and menus on page 91 for more
information.
82 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Business logic and customizing the user experience
When you create an object definition, Rollbase automatically creates the following pages for you: records list,
new, view, edit, status change, mass update, search results, and selector list. If you later modify the underlying
object definition, for example, by adding a field or attribute, you can choose which pages Rollbase will add the
new component to. Pages, the page editor, and grid controls on page 362 describes how you can modify pages
by adding and removing components.
The following table describes each page type:
Type Purpose
Generic A generic page is not associated with a particular
object. When you create a new generic tab, Rollbase
creates a generic page for it. You can use a generic
page to render dashboards and other information such
as HTML and script components, and to calculate
summary information using formula and template fields.
See Creating tabs and pages on page 362 for
information about creating generic pages.
Record list A record list page contains a view component that lists
records of that object type. See an example of a
records list page.
New record A new record page provides the controls for creating
a new record. To open this page when viewing a list
of object records, click New <object_name>. See an
example of a new record page.
View A view record page displays an existing record. Open
a view page when viewing a list of object records by
clicking the record name. See an example of a view
record page.
Edit An edit record page provides the controls for editing
an existing record. Open an edit page from a list of
records by clicking Edit. See an example of an edit
record page.
Status change A status change page is used to confirm workflow
status changes to an existing record of a particular
object type. You can optionally include other fields in
this page to be updated. Different versions of this page
can be associated with different statuses. See
Workflow overview on page 256 for more information.
Mass update A mass update page provides the controls for updating
a group of selected records simultaneously. The default
mass update page runs the onUpdate trigger. You
can create different versions of this page to provide
different mass update functionality. View a mass
update page from a records list page by selecting one
or more records and selecting Mass Updates from
the tools overflow menu. See an example of a mass
update page. See Updating multiple records on page
174 for information on making mass updates.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 83
Chapter 4: Designing a Rollbase application
Type Purpose
Quick create A quick create page is a dialog that allows you to
create a new record. See an example of a quick create
page.
Search results A search results page contains a view component for
all records that match search criteria. See an example
of a search results page.
Selector A selector page appears in a pop-up window, enabling
users to select one or more records for a ListView,
Grid Control, Multi select pick-list, record attach,
ListView filters, Custom report filter fields in the New,
Edit, Mass update, Quick create, status change pages
across the application. You can open a selector page
to select required number of records by clicking the
selector icon. Configure the maximum number of
records based on your business need for selection in
the MaxRecordsInSelector field of the Shared
Properties. If the number of records selected exceeds
the maximim number of records configured in the
Shared Properties, Rollbase will throw an alert. The
maximum number of records that can be configured
for selection is 1000. See an example of a selector list
page.
Portal page A portal page gives portal users access to object
records or functionality. You can assign the same
portal page to multiple portals. For more information
about portals, see Rollbase portals on page 524
84 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Business logic and customizing the user experience
Record list page example
This record list page example from a corporate room reservation system shows the controls available to add
or edit furniture records.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 85
Chapter 4: Designing a Rollbase application
New record page example
This example new record page from a corporate room reservation system has controls for adding related
furnishings.
86 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Business logic and customizing the user experience
View page example
This example view page from a corporate room reservation system shows record data. The System Info page
tab contains information from system fields such as who created the record and when it was last updated.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 87
Chapter 4: Designing a Rollbase application
Edit page example
This example edit page from a corporate room reservation system allows users to edit the record and add or
edit the related furnishings and devices.
88 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Business logic and customizing the user experience
Mass update page example
This example mass update page from a corporate room reservation system allows users to edit multiple records
at the same time.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 89
Chapter 4: Designing a Rollbase application
Quick create page example
This example quick create page from a corporate room reservation system allows users to quickly create
furniture records.
Search results page example
This example search results page from a corporate room reservation system displays the results of searching
for rooms that contain "conference".
90 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Business logic and customizing the user experience
Selector page example
This example shows a selector page from a corporate room reservation system. Room records are related to
Furnishing records. To specify which furniture is in a room, users can click the Furnishings lookup field to see
the list of furnishings.
Application tabs and menus
The application menu bar contains tabs. Each tab can have child menu items. For example, in the screens
below, Titles, Check Outs, and Check Ins are tabs that Rollbase created when the objects were created.
Available Titles is a child menu that was added to the Titles tab.
The following screen shows the tabs in the Traditional UI blueprint:
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 91
Chapter 4: Designing a Rollbase application
The following screen shows the tabs in the Modern - Vertical Menus UI blueprint:
Menus are child components of tabs. You can modify a tab to change it into a menu of another tab and you
can promote a menu to be a tab.
You can create tabs of any of the following types:
• Generic tab — Associated with pages that contain custom content such as arbitrary views, charts, HTML
or script components, or third party widgets.
• Object tab — By default, when you create an object, Rollbase creates an object tab for the records list page,
which lists all records of that object type. Controls and tab menu items on this page allow the user to navigate
to other pages for the same object, such as the new and view pages. See Application page types on page
82 for more information about the pages Rollbase creates for objects.
• Web tab — Contains an embedded website and allows you to embed other sites or web-based applications
into your Rollbase applications.
See Creating tabs and pages on page 362 for more information.
You can edit application tabs to add and reorder menus and set permissions that determine which menu items
will be visible to users. You can organize navigation by creating new menus, removing menu items, or changing
tabs to be child menus of other tabs (tabs that are assigned a parent become menus of the parent).
For more information about editing tabs and menus, see Customizing application tabs and menus on page 397.
92 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Business logic and customizing the user experience
Tabs on pages
You can organize sections on record view, edit, and new record pages using page tabs. This helps to visually
separate components on a complex page. For example, the following screen shows the new page for User
records. It contains multiple sections, each with multiple fields. A user would have to scroll to enter the data
for all fields:
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 93
Chapter 4: Designing a Rollbase application
This example shows the same page, but with page tabs that organize the sections.
Tabs on view pages are displayed on demand when the user selects them. The content of these tabs is
generated and sent via AJAX as needed. This may present a problem if tabs include JavaScript. In this case,
you can check the Do not use AJAX loading for Tabs on the page's Properties page. On pages that allow
users to browse records, the selected tab continues in focus as the user clicks Next or Prev. The tab selection
is reset to the first tab if a user goes back to the list of records.
See Page tabs on page 378 for information about enabling, editing, and adding tabs to pages.
Page components
The following table lists the main page components. Rollbase adds some to pages when they are created; you
can add others by dragging them onto a page from the list of available components in the page editor.
Many components have page-level properties that can be changed in the page editor. See Adding and configuring
components on page 371 for details.
94 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Business logic and customizing the user experience
Component Use Where Available
Form Contains buttons to edit, cancel, or Added automatically to view, new,
submit a form. edit, status change, and mass
update pages. Cannot be deleted.
Chart Renders the selected chart. Generic and record list pages - if at
least one chart is created for this
object.
Gauge Renders the selected gauge. Generic and record list pages - if at
least one gauge is created for this
object.
Comments table Renders a list of comment records View page
created on a particular record.
Audit trail Renders a list of audit trail records View page
created on particular record.
View List of records which can be paged, Generic, record list, and selector
sorted, filtered, grouped, etc. pages - only one view component
per object type can be placed on a
page.
Lookup field When clicked, displays either a Edit page
selector page or a picklist that
allows users to select one or more
related records.
View of related records List of records related to or having View page
a relationship with the record
currently being viewed.
Recurrent events List of recurrent instances of event View page
or task
Detailed search A configurable search component Generic and record list pages
providing a way to allow users to do
field-specific searches (for instance,
Amount>Min AND Amount<Max).
Field Renders an object field in view or View, new, edit, status change, and
edit mode. View mode (in certain mass update pages. When new
cases) allows inline editing using fields are created, each field is
the icon. Many field types have added to the Default New Fields
properties that can be configured at Section of each page.
the page level.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 95
Chapter 4: Designing a Rollbase application
Component Use Where Available
Grid control A configurable component used in New, edit, view, and status change
create/edit pages to create and edit pages - No more than one grid
a group of records related to the control can be used on any given
current (master or parent) record. view page.
For more details, see Using grid
controls to manage multiple records
on page 383.
Organization tree Displays an interactive hierarchy of Record list pages (for LDF objects
locations, departments, or functions. only)
Report link Link to a particular report Generic, record list, and view pages
HTML component Template-based HTML component All pages
Script component Template-based script component All pages
The Rollbase calendar
The Rollbase application includes a calendar. You can use the calendar to create meetings and other events,
and to track tasks and their workflows. You can add the calendar to any application, and you can synchronize
the Rollbase calendar with other calendar software. For example, meetings you add to the Rollbase calendar
can appear in your Google calendar.
The calendar displays records whose object definitions have an Event or a Task attribute, as well as records
of the built-in objects Meeting and To-Do. Administrators can add the Calendar object to any application to
include its built-in functionality.
You can view the calendar by day, work week, week, month, or agenda. You can filter any calendar view by
object type and by records assigned to you, to all users, to administrators, or to users with a specific role.
Records marked as Private that are not assigned to you do not appear in your calendar.
96 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Business logic and customizing the user experience
You access the calendar through the Rollbase application or any application that includes the Calendar object.
You can use the Rollbase calendar functionality to:
• Create calendar events and tasks in any of the following ways:
• From the calendar itself: Double-click a day, select the type of entry to add, and click Create.
• From the Rollbase application: Add Meeting or To-Do records.
• From any application: Add a record for any object that includes the Task or Event attribute.
• As an administrator, add a Calendar component to any generic page using the page editor. For example,
you might have object definitions for training classes, conferences, and project deadlines. Using a Calendar
view, you can quickly see when you have any of these events planned and manage them accordingly.
• As an administrator, synchronize Rollbase calendar events (but not tasks) with Google calendar. See
Synchronizing with Google Calendar on page 634 for details.
• For other calendars, such as Microsoft Outlook, you can export records individually in the standard iCal
format. Click the record you want to export and from the More Actions menu, select iCal. Rollbase exports
the record locally and the Rollbase footer shows the exported file's name. Click the downloaded file to
open it in Outlook and Outlook will prompt you to take the appropriate action.
Calendar views
The calendar includes five views. To change the view, click its name in the calendar toolbar:
If the screen is too narrow to display the views, select the view from the drop-down menu in the toolbar:
Available views include:
• Day — Displays a single day with events.
• Work Week — Displays Monday through Friday with events.
• Week — Displays Sunday through Saturday with events.
• Month — Displays all days in the month with events listed for each day.
• Agenda — Displays a week's worth of events by date.
For any event, double-clicking the link in any view except the Agenda view opens a dialog that displays more
information; you can click View or Edit to see more information or to modify the event.
Double-clicking on a day or hour launches a dialog to create a new event. See Adding events to a calendar on
page 98 for details.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 97
Chapter 4: Designing a Rollbase application
Administrators can configure the calendar to set its default views and to specify the time period to display in
the Day, Work Week, and Week views. See Configuring the calendar on page 98 for details.
Configuring the calendar
Administrative users can configure the calendar to specify the default view and the range of hours to display.
To configure the calendar:
1. In the calendar toolbar, click configure:
The Configure Calendar Component window opens.
2. Configure the desired properties:
• Default View: Day, Work Week, Week, Month, or Agenda)
• From Hour: Starting hour (0 to 10) to display on Day, Work Week, and Week views
• To Hour: Starting hour (17 to 24) to display on Day, Work Week, and Week views
3. Click Save.
Adding events to a calendar
You can add any of the following event records to a calendar:
• A Meeting record — The Meeting object is defined in the Rollbase application and it includes the Event
and Workflow attributes.
• A To-Do record — The To-Do object is defined in the Rollbase application and it includes the Task and
Workflow attributes.
• A record whose object definition includes the Event or Task attribute.
See Object attributes on page 79 for more information about the Event, Task, and Workflow attributes.
1. Do one of the following:
98 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Business logic and customizing the user experience
• Double-click a day, select the type of event to add, and click Create:
• From the Rollbase application, create a Meeting or To-Do record.
• From any application, create a record for any object that includes the Task or Event attribute.
The New page for the type of record you are creating opens.
2. Enter the fields for the new record:
• For records whose object definition includes the Event attribute, fields include Subject, Location,
Date/Time, Duration, Assigned To, Description,Private, and Pop-up Reminder. The following screen
shows the New Meeting page:
• For records whose object definition includes the Task attribute, fields include Subject, Assigned To,
Due Date, Priority, Description, and Private. The New To-Do page, shown below, also includes
Workflow Status because it has the Workflow attribute:
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 99
Chapter 4: Designing a Rollbase application
3. Click Save. Rollbase creates the record and the event appears in the calendar.
Recurring calendar events and tasks
You can replicate calendar event and task records using a recurring date pattern. To do so, open the record
view page for the event or task you want to replicate and select Recurring Events or Recurring Tasks from
the action menu:
100 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Business logic and customizing the user experience
The Recurring Events or Recurring Tasks page opens for the record. Select the Start Date and End Date
and select the recurring options: Daily, Weekly, Monthly, or Yearly. Depending on the option, select the
day(s), week(s), and/or month(s) for the recurring event or task. Rollbase clones the selected event or task
according to the selected pattern. The number of recurring events cannot exceed 300.
In the following graphic, a recurring meeting that occurs every Monday, Tuesday, and Wednesday is created:
To view and manage recurring instances of events or tasks, add the appropriate Recurring Events component
to the record view page in the page editor. The component is either Meeting, To-Do, or an object with the
Event or Task attribute and must be placed in its own section of the page. Edit the component to select its
view. Recurring events or tasks will now appear in the original record's view page.
Calendar notifications
Event records include a notification, which sends an email notification when an event is added to the calendar.
The email includes a link to the record's information in Rollbase.
If logged in to Rollbase, users will also receive pop-up notifications when a meeting assigned to them is about
to start. Timing for that notification is determined by the Pop-up Reminder field on a record. Reminders are
displayed only once.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 101
Chapter 4: Designing a Rollbase application
Setting up accounts for testing
You can easily test your Rollbase application as you build it by switching between application interface and
setup pages. The applications, pages and controls that end-users see depend on the user's role and permissions.
To experience the application as end-users will experience it, you can create test user accounts.
You set up a user account by creating a new User record for that user. The User object is a built-in component
of the Rollbase application. You can add the User object to your application for convenience. Rollbase provides
several built-in roles, including Administrator. You can create roles specific to a particular application. The
Role object is also a built-in object, but is only available from administrative setup. See Role-based access
control on page 648 for more details.
To create a User record for testing, you will need an email address that differs from the associated with your
Rollbase account. You can create several to test using different combinations of roles and permissions.
Distribution options
Rollbase offers hosted and private cloud environments:
• Progress Software manages and maintains the hosted Rollbase environment.
• You manage private cloud environments by installing Rollbase on your own infrastructure or on any cloud
platform.
In both hosted and private cloud environments, Rollbase tenants are virtual spaces that define settings and
applications for a group of users. The person who initially signs up for a Rollbase account becomes an
administrator for a tenant. A tenant can act like a development sandbox and be used mainly by one or more
developers. Alternatively, a tenant can be used for development and when applications are stable, they can
be exposed to end users.
You can provide access for end users to a Rollbase application in the following ways:
• By creating accounts for them to access the application in your tenant. This includes creating User records
and setting application permissions.
• By creating a portal that exposes all or a subset of application functionality. See Portal Overview.
• By generating the application as XML, which can be installed in any Rollbase tenant.
• By publishing your application to the Rollbase Marketplace. For more information, see Publishing to the
Marketplace App on page 693 and Using the Progress Rollbase Marketplace on page 692.
If you plan to distribute your application to other tenants, Progress recommends thinking about installation and
upgrades early in the design process. Try publishing your application to the Marketplace or generate it as XML
and then test the installation before distributing it to others. For more information, see Distributing applications
in XML format on page 703.
Portal Overview
Portals provide a flexible way to build and expose external-facing applications in public websites or intranets
for external users such as website visitors, partners, or employees on an intranet. With Progress Rollbase, you
can create portals to allow just about any type of external user to access specific application functionality such
as creating, editing, searching, and viewing object records. Portals consist of an arbitrary number of pages that
form a cohesive website. Portals can be designed to adopt the look and feel of any website.
102 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Distribution options
Portals often expose a subset of Rollbase application functionality to a specific set of users. For example, a
Rollbase application for managing sales leads might have a portal integrated with your website to collect
information submitted by website visitors. An application for employee management might have a portal for
self-service access to employee profile information, company directory, and benefits information.
For more information on designing and developing portals, see Rollbase portals on page 524.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 103
Chapter 4: Designing a Rollbase application
104 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
5
Laying the foundation
Objects, their fields, and the relationships between them form the data model for a Rollbase application. From
these, Rollbase generates a set of pages for viewing, creating, editing, and deleting records. The topics in this
section describe how to work with applications, objects, and records.
You can create a Rollbase app in different ways, depending on your requirements:
• If you are starting from scratch and have an initial set of objects in mind, use the Quick Create wizard.
The Quick Create wizard walks you through a series of steps to create an application and an initial set of
objects. You can also specify relationships between the objects. The Quick Create wizard does not support
all advanced field and attribute types, but you can easily edit the application and objects later to add them.
See Getting started with the Quick Create wizard on page 106 and Editing applications on page 109 for more
information.
• If you want to use objects that already exist in your tenant, create the application first as described in Creating
an application your way on page 108, and edit it to add the objects, as described in Editing applications on
page 109.
• It you want to import applications, import data from an existing data source or create external objects that
map to other data sources, see Integrating with outside sources on page 583
The following videos provide a quick orientation to Rollbase:
• A tour of the Rollbase interface
• A demo of how to use the Quick Create Wizard
• A demo of how to add business logic
• A demo of how to customize the user experience
• An overview of how to distribute your applications to end-users or sell them
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 105
Chapter 5: Laying the foundation
The topics in this section describe how to create and manage applications and objects.
For details, see the following topics:
• Getting started with the Quick Create wizard
• Creating and managing applications
• Creating and managing objects, fields, and relationships
• Views
• Relationships between objects
• Working with records
Getting started with the Quick Create wizard
The Quick Create wizard walks you through the steps required to create a Web application and add objects
and relationships to it. Watch a short video that takes you through the steps here: Using the Rollbase Quick
Create wizard
Follow these steps to use the Quick Create wizard:
1. Launch the Quick Create wizard in one of the following ways:.
• From application pages: select New Application from the Rollbase menu.
• From Setup pages: Click New Application in the sidebar.
The Create a New Application dialog opens.
2. In the New Rollbase Web App section, click Guide Me Through It.
The Quick Create wizard displays:
106 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Getting started with the Quick Create wizard
3. Enter a name and optionally, a description for your application..
4. Click Next.
The Create Objects page displays.
5. Follow these steps to add object definitions:
• In the Object Name field, enter the singular form of your object name. Rollbase will use the plural form
for lists of objects.
• From the Attributes drop-down list, select desired attributes. See Object attributes on page 79 for more
information about attributes.
• To add more objects, click Add Object.
• When you are finished, click Next.
The Add Fields page displays, with the first object highlighted.
6. To add fields, follow these steps:
• Enter a singular name in the Field Name box.
• From the Field Type drop-down list, select a data type. For a description of field data types, see Field
types on page 1302.
• Optionally, enter a Default Value that will populate this field when users create new records.
• To add another field, click Add Field.
• To add fields to another object, select that object in the left pane.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 107
Chapter 5: Laying the foundation
• When you are finished, click Next.
The Relationships page displays.
7. In the Related To field of the object to which you want to add a relationship, click Select. Choose the
appropriate relationships as follows:
a) Check the info graphic to visualize relationship cardinalities.
b) If the relationship cardinality icon has arrows as shown in the example below, click them to display all
of the available cardinalities.
c) Click + to select a relationship or - to remove one.
d) When you are finished with relationships, click Submit.
An overview of the application displays. You can see the pages Rollbase created for you and you can view
and edit your application.
Creating and managing applications
You can quickly create a new Rollbase application in the following ways:
• Create an application from scratch.
• Install an application that has been distributed to you in XML format.
• Create an application that includes existing objects.
• Create an application by importing from external data sources.
Creating an application your way
When you create an application your way, you add objects to it. These can be objects that exist in your tenant
or new objects that you create. Follow these steps to create a new Rollbase application your way:
1. Launch the Create a New Application dialog in one of the following ways:.
• From application pages: select New Application from the Rollbase menu.
• From Setup pages: Click New Application in the sidebar.
The Create a New Application dialog opens.
108 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Creating and managing applications
2. Choose your preferred option for creating an application:
• New Rollbase Web App — Choose from the following options:
• Click Guide Me Through It to launch the Quick Create Application wizard.
• Click Let me build it my way to create an empty application to which you will add components.
• Install from Marketplace — Opens the Rollbase Marketplace.
In Rollbase Private Cloud, this option is available only if the master tenant administrator has enabled
Marketplace. For information about enabling Marketplace, Enabling or disabling Marketplace in Rollbase
Private Cloud on page 695.
• Install from App Library — Opens the Rollbase Marketplace window, which displays a list of applications
you can install.
• Create from External Data — Creates an application by importing from (follow the link for more details):
• A Rollbase application XML file
• An active Salesforce.com application
• A Microsoft Access database
• An OpenEdge Object Service using a JSDO catalog file
• Create from Existing Objects — Creates a new application and allows you to add existing objects to
it.
The remaining steps vary depending on the option you choose.
Editing applications
The application setup page allows you to view and edit the following for an application:
• The application definition
• Application properties
• Application components - add new components or edit existing components
To open the application setup page and view or edit an application:
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 109
Chapter 5: Laying the foundation
1. From the application switcher drop-down available next to the application name:
• To navigate to settings for the current application, click App Settings.
• To navigate to settings for a different application, hover your mouse pointer over the application and
click its associated Application Settings icon.
2. Perform any of the following operations on the application setup page:
• Add or edit the application components (such as tabs or objects) listed in the box below the application
name:
Click the component link to navigate to the component area. For example, click Tabs to navigate to a
table listing the application's tabs.
• Click Delete to delete an application. See Deleting an application on page 124 for more information.
• Click the More actions... drop-down menu to perform advanced operations. See Application actions on
page 113 for the options available in this menu.
• Click the Theme Preview icon to try out different themes for your application. See Using the Theme
Preview mode on page 120 for more information.
• Click Post Install Scripts to add one or more post install scripts to the application. See Post install
scripts on page 127 for details.
• Click Edit to view and edit application properties:
• Deployment status specifies:
• Whether an application is deployed. If the application is deployed, all users with permissions to
view the application will see it when they log in. If the application is not deployed, only users with
permissions who have an administrator role will see it.
• Whether an application is hidden. If the application is hidden, it will not be listed in the application
switcher.
• Whether any field-level help you have supplied in component definitions will be available to
end-users who click ?.
• Application name and Description
• An optional Custom Logo to appear in the upper-left corner of each page of the application. The
maximum size is 256 KB. Additionally, you can choose to hide an application logo by selecting the
Hide Logo check box.
• Properties in the New UI Specific Settings area only apply when using the New UI:
• UI Blueprint — Controls how the application navigation and various menus inside the application
are rendered. The page content does not change across blueprints. Two UI blueprints are available,
Traditional and Modern - Vertical Menus. See UI Blueprints on page 401 for more information.
• Application Theme — By default, the pages of your application use the Default theme to display
their components. You can change the look and feel of you application by selecting a theme from
the Application Theme list.
110 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Creating and managing applications
• Field Labels Render Mode — Specifies how labels are rendered with regard to field values. By
default, labels are to the left of field values on desktops and above field values on mobile devices.
You can change the default by selecting a different option:
• Use Horizontal Responsive Design — By default, Rollbase applications use vertical responsive
design. Select this check box to use horizontal responsive design instead. See Vertical and
horizontal responsive design on page 433 for more information about responsive design.
• Use Native Calendar and Time Control on mobile devices — Select this check box to use
native date and time controls on mobile devices.
• Right to Left Text Direction — Select this check box to use right to left text direction. This feature
is to support languages, such as Arabic and Hebrew, that are written from right to left.
• Notifications Position — Specifies where to position notification messages based on the context
of your application and set to display at the center, top corner or bottom corner. Select Centered
to position a notification at the center. Select Top Corner to set the position to the upper right
corner (default). Select Bottom Corner to set the position to the lower right corner.
• Enable GridControl Selective Edit — Select a required record count range to enable selective
editing of related records in a page.
Note: When grid control component is rendered in selective edit mode, you can click edit icon
against a grid row to enable editing. Additionally, double-clicking the grid row (for TabularGridControl
forms) will also enable editing. Enabling grid control for selective editing will affect all grid
components in an application.
• Bootstrap Version — Select a bootstrap version to be used during runtime of the application.
Only users who have an administrator role have the permission to make a selection. By default,
Bootstap version v4.0.0 is selected.
Note:
• This property is applicable only in the new UI.
• When you import an application (Rollbase version less than 5.2), by default, bootstrap version
4.0.0 is applied.
• When you opt to use CDN, the bootstrap files are loaded from CDN based on the bootstrap
version selected.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 111
Chapter 5: Laying the foundation
• Properties in the Corticon Decision Server area let you configure up to three Corticon Server
instances to access from Automating business decisions with Corticon rules on page 277 triggers.
• Server to use — The selected radio button determines the server instance used by triggers in
this application. Defaults to Development.
• Development or test server — The URL of the server instance to access in a development
environment
• Staging server — The URL of the server instance to access in a staging environment
• Production server — The URL of the server instance to access in a production environment
• User Name / Password — The credentials used to access each server instance.
• Tabs - You can add tabs from the Available Tabs column, remove tabs from the Selected Tabs
column, and reorder the Selected Tabs column using the arrow buttons:
112 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Creating and managing applications
• Core Objects, Dependent Objects, and User Roles that must be included in the application when
it is published.
Application actions
The More Actions menu on the application setup page offers additional options to manage your application.
To access More Actions:
1. From the application switcher drop-down available next to the application name:
• To navigate to settings for the current application, click App Settings.
• To navigate to settings for a different application, hover your mouse pointer over the application and
click its associated Application Settings icon.
2. Click More Actions:
View Diagram
The More actions menu on the application setup page includes a View Diagram option. This option generates
a Entity-Relationship (ER) UML diagram that helps you visualize application objects and relationships. The
UML diagram is useful during development and is also useful for getting an overview of applications you did
not develop but installed from XML. The ER UML diagram is generated by third party JavaScript library(mx-graph)
and, for large applications, can take a few minutes to load.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 113
Chapter 5: Laying the foundation
The following ER diagram shows the objects in a simple Library application:
The UML diagram is generated in three different layouts — Organic, Hierarchical, and Circular. By default,
Organic is selected for application diagrams and Hierarchical is selected for workflow process.
In addition, you can move the nodes, drag the edges to proper coherent and readable orientation. Clicking on
layout buttons will re-render the graph in a different ordering. You can click Save ss PNG to to export the graph
as an image.
Note: You can view the object level UML diagram by navigating to Objects from Application setup page and
selecting the required object's Workflow Processes>View Diagram or Workflow Processes>Default options.
Application Tree
The More Actions menu on the application setup page includes an Application Tree option. This option allows
you to view all application components in a tree. Components with errors are highlighted in red. Expand parent
nodes to see child components.
114 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Creating and managing applications
Generate XML
The More Actions menu on the application setup page includes a Generate XML option. The Generate XML
option allows you to generate and save an application in XML format. The resulting XML can be installed in
other Rollbase tenants. The XML files for complex applications can be over 5MB. After the file is generated,
choose Save or Save As to save a copy locally.
Applications with errors will not generate XML. If this is the case, try creating an application tree, which will
show you any components with errors.
Options available when generating XML include the following:
• The version of the application to be exported as XML. This value is auto-incremented each time you generate
new XML for the application.
• Lock status settings for users in destination tenants:
• Select Unlocked to allow users to modify all parts of the installed application.
• Select Partially Locked to allow users to modify only unlocked objects, menus and portals. If you select
this option, select the check box next to each application component you want to lock.
• Select Locked to disallow users from modifying any part of the installed application.
In the following graphic, the user has selected Partially Locked and has selected the Child object to be locked:
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 115
Chapter 5: Laying the foundation
See Publishing and distributing applications on page 691 for more details.
Update from XML
The More Actions menu on the application setup page includes an Update from XML option. Use this option
to upload a Rollbase application XML file and install updates. For information on installing application updates
from XML, see Installing and updating applications from XML on page 126.
Performance Audit
The More Actions menu on the application setup page includes a Performance Audit option. Use this option
to:
• Validate all formulas used by your objects and display any errors.
• Check whether formulas are using loops through related records. Loops are inefficient and should be
replaced with Query API methods whenever possible.
• Check whether views are using template and formula fields that can decrease performance.
In the following graphic, the performance audit for the Order Management application reports three potential
performance issues:
116 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Creating and managing applications
Custom sidebar
The More Actions menu on the application setup page includes an option to add a Custom Sidebar. In the
classic UI, when you add a custom sidebar, it appears on the left sidebar and is included in the published
application. You can add your own component using HTML or JavaScript. You can also use widgets or gadgets
from providers such as Google or Yahoo. You can also use client-side JavaScript functions. See Client-side
JavaScript on page 1131 for more information.
Header and footer
The More Actions menu on the application setup page includes an option to add a custom header and footer
to the application as shown below.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 117
Chapter 5: Laying the foundation
See Customizing the header and footer on page 395 for details and an example.
Set Mobile-Web Options
The More Actions menu on the application setup page includes an option to Set Mobile-Web Options. Use
this option if you want Rollbase to generate a Mobile-Web (formerly known as Mobile Edition) version of your
application. See Supporting mobile users on page 551 for more information.
Translation
In tenants configured for additional languages, the More Actions menu on the application setup page includes
an option for Translation. You can create an Excel spreadsheet that translates (or localizes) your application
into a foreign language. For more information on localization, see Localization on page 206.
Attach String Tokens
The More Actions menu on the application setup page includes an option to Attach String Tokens. You can
attach selected strings for localizations to your Rollbase application. Attached string tokens are published and
installed as part of the application.
118 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Creating and managing applications
For more information about string tokens, see Creating and using string tokens on page 193.
View Installation Log
The More Actions menu on the application setup page includes an option to view the installation log for the
application. If you are experiencing problems running an application, the installation log might provide information
about problems during installation. When you click Installation Log, a popup window opens and displays the
installation log for each application installed in your tenant.
The example below is a portion of the installation log for the Order Management application:
Application permissions
The Permissions section on the application setup page allows you to manage permissions by user role and
by individual users. Permissions set for a user override those set for roles, allowing fine-grained access control.
In addition to permissions set at the application level, you can set relationship-based permissions and role-based
field-level permissions.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 119
Chapter 5: Laying the foundation
To set application permissions:
1. On the application setup page, click Permissions in the ribbon below the application name or scroll down
to the Permissions area of the page.
2. Click Edit Permissions. A new page opens and displays the current permissions for user roles:
3. If desired, click the check box for a user role to toggle its permission for the application.
4. To set the application permission for a user, click Select User. A popup window opens and displays the
users. You can navigate through the list of users or you can search for a particular user. Click the user for
whom you want to set the application permission.
5. The user appears in the table under Individual Users. Click the check box for the user to toggle its permission
for the application.
For information about managing application permissions and access control, see Security and access control
on page 643.
Using the Theme Preview mode
By default, application pages use the Default theme. The Theme Preview mode enables you to try out different
themes and apply a theme that meets your requirements. There are two ways to use the Theme Preview mode:
• Administrators can change the look and feel of an application by applying a different theme. See Selecting
a theme for an application on page 120 for details..
• All users, including non-administrative users, can select a theme to use for all applications, regardless of
the theme chosen for each application by an administrator. See Selecting a theme for a user on page 122
for details.
Note: The capability for users to set theme preferences is enabled by default. An administrator can disable
this capability by selecting Setup Home > Preferences and deselecting the Allow users to set individual
theme preference check box.
Selecting a theme for an application
An administrator can change the theme for an application. The application will use the selected theme for all
users unless a user has selected a different theme for all applications (see Selecting a theme for a user on
page 122).
120 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Creating and managing applications
To apply a theme to an application using the Theme Preview mode:
1. Do one of the following:
• On an application page, click Theme Preview in the application switcher:
• On the application's Setup Application page, click Theme Preview:
The application opens in the Theme Preview mode.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 121
Chapter 5: Laying the foundation
2. Select a theme from the drop-down menu in the Application Theme - Preview bar. The appearance of the
application page changes based on the theme you select.
3. You can:
• Click Apply. The Set Application Theme dialog opens. Click OK to apply the new theme. The Theme
Preview mode closes and the new theme is applied to the application.
• Click Close to exit the Theme Preview mode without changing the theme.
Selecting a theme for a user
Any user can select a theme to use for all applications. The user's theme selection overrides any theme selected
by an administrator for a particular application.
To select a theme to use for all of your applications:
1. From the Rollbase menu, select My Theme:
122 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Creating and managing applications
The application opens in Theme Preview mode.
2. Select a theme from the drop-down menu in the My Theme - Preview bar. The appearance of the application
page changes based on the theme you select.
3. You can:
• Click Apply. The Set this theme as my preference for all applications dialog opens. Click OK to apply
the new theme. The Theme Preview mode closes and the new theme will be used for all of your
applications.
• Click Close to exit the Theme Preview mode without changing the theme.
To revert your theme preference back to the theme set for each application, select Select a Theme from the
drop-down menu in the My Theme - Preview bar and click Apply. A dialog opens; click OK to unset the user
theme preference.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 123
Chapter 5: Laying the foundation
Note: You can also set and revert your theme preference by selecting My Profile from the user profile menu
and selecting My Preferences. This allows you to set your theme preference without using the Theme Preview
mode.
Note: While the capability for users to set a theme preference is enabled by default, administrators can disable
it. See Using the Theme Preview mode on page 120
Deleting an application
To delete an application:
1. On the application setup page, click Edit. Rollbase displays the application's properties.
2. In the Deployment Status area, uncheck the This application is deployed check box.
3. Click Save. Rollbase returns to the application view page.
4. Wait for at least one hour.
5. Click Delete.
Deletion of an application has the following consequences:
• All objects (and corresponding data records) that are assigned to the deleted application and are not assigned
to any other application will be permanently deleted.
• All menus, portals, and hosted files that are assigned to this application and are not assigned to any other
application will be permanently deleted.
• The application record will be permanently deleted.
Deletion of an application does not cause deletion of system objects.
Rollbase requires the following prerequisites to avoid accidental deletion of important information:
• Before deleting an application, it must be undeployed.
• After undeploying an application, you must wait at least one hour before deleting it.
Installing applications
You can install existing Rollbase applications in one of the following ways:
• Install an application from the Marketplace.
• Install an application from the Application Directory (Rollbase Private Cloud only).
• Install an application from XML.
You can define post install scripts for an application that execute after the application is installed, after the
application is updated, and after the application is installed as part of customer creation. See Post install scripts
on page 127 for more information.
Installing an application from the Marketplace
Users with the Administrator role can log into their Rollbase account to install Rollbase applications from the
Marketplace.
124 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Creating and managing applications
Note: Installing an application from Marketplace is not available for a Support login.
The following procedure describes how to navigate to and install an application:
1. Open Marketplace:
• From the Rollbase menu, select Install Applications (or New Application and click Install from
Marketplace).
• Use the Marketplace URL:
• Marketplace on the Private Cloud: http(s)://<host-name>/master/marketplace
Note: You can configure your Private Cloud Marketplace URL in Shared Properties on page 786.
• Marketplace on hosted Rollbase : https://www.rollbase.com/master/marketplace
2. Search the Marketplace in one of the following ways:
• Using application categories: Browse and open a category from the Categories pane. Select an
application to navigate to its home page.
• Using the search box: Use Marketplace search to navigate to an application's home page.
• Using the featured, popular, or new apps sections: Find and select an application from the Featured
Apps, Popular Apps, or New Apps sections, after which its home page opens.
3. To install:
• A free application in your tenant, click the application name and then, click Install.
• A paid application, click Learn More. Follow the publisher's instructions to purchase and install the
application in your tenant.
• An application update in your tenant, click Update. You can update all the components of an application,
or retain the existing components and update the application only with new components.
Installing and updating applications from the Marketplace App
In Rollbase Hosted Cloud, Marketplace replaces the Application Directory. Wherein, Marketplace is the
platform to publish and distribute applications.
For more information about publishing and distributing applications using Marketplace, see Using the Progress
Rollbase Marketplace on page 692.
1. From the Rollbase Menu, select Install Applications.
2. Browse the list of available applications to find the application you want to install.
3. Click an application name for more information about the application, including whether a test drive is
available, user reviews, and whether an application XML file is available for installing the application to your
Private Cloud.
4. If you want to test drive the application, and test drive is available, click Test Drive. The application opens,
allowing you to try it out before installing it. Alternatively, click Install.
The application is installed and you can start using it.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 125
Chapter 5: Laying the foundation
Updating an Application
To check for updates to an installed application:
1. From the application switcher:
• To navigate to settings for the current application, click App Settings.
• To navigate to settings for a different application, hover your mouse pointer over the application and
click the settings icon.
2. Click Check Updates.
3. If updates have been published and the version of the installed application is lower than the currently
published version, click Install Updates to update the application.
Some applications are marked as Managed, meaning that the publisher retains full control of the application's
structure; you cannot customize any of its components. Only the publisher can customize managed applications.
See Installing application updates on page 947 for more information.
Overriding Changes
When installing updates from the Marketplace, note the Override Changes check box below the Install
Updates button. For unlocked applications, this check box controls important behavior:
• If checked, Rollbase overwrites existing application components with those in the new application version.
This happens for locked and partially locked applications regardless of whether this check box is checked.
• If unchecked, Rollbase only creates new application components and will not overwrite existing components
to preserve any customizations made since the previous install or update. Note that locked and partially
locked applications receive all updates for locked components, but unlocked components will not be modified.
The following provide examples of how overriding works:
• If you created a portal and the updated application does not have a portal with the same name, your portal
will not be overwritten, regardless of whether Override Changes is checked or not.
• If you added three fields to an object and Override Changes is checked and/or that object is locked by the
application publisher, updating will override the object and your three fields will not be available. Any pages
to which the fields were added will no longer show those fields.
Installing and updating applications from XML
If you received a Rollbase application as an XML file, you can install it in your own tenant. You can also install
application updates from a Rollbase application XML file.
To install an application from XML, follow these steps:
1. Navigate to the Setup home page:
• From an application page, do one of the following:
• Select Setup Home from the Rollbase menu.
• Select Setup Home from the application switcher
126 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Creating and managing applications
• From a setup page, select Setup Home from the application switcher
2. In the APPLICATIONS SETUP section, click Applications
Rollbase displays a list of existing applications:
3. Click Import From.
The Import From screen opens:
4. Select Progress Rollbase XML file and click Next.
The Install or Update from XML screen opens:
5. Click Choose File and browse to select the application XML file.
6. Click Next.
Rollbase displays a tree of components included in the application as follows:
• For new installations, you have the option to uncheck boxes for locked components to avoid having them
installed as part of the application.
• For updates, if the application is fully locked, all components will be updated/created/deleted automatically
during the installation process. If the application is partially locked, all locked components will be
automatically updated/created/deleted during installation. You have control over what happens to unlocked
components; uncheck boxes for components you do not want to update.
• If a component was deleted from the latest version of the application but is present in the tenant where
you are installing the update, this component will be listed at the bottom of the tree. Check the box next
to each deleted component if you want to delete that component as well. This is a safety precaution
designed that allows you to bypass such deletion.
• Components deleted in the latest version of the application will be deleted in the destination tenant if the
Override Changes box is checked. If an application or portal page is updated, the page's entire structure
(sections, cells) will be replaced by the structure defined in the application XML.
7. Review the application tree and uncheck boxes next to components you do not want to install/update.
8. Click Install to continue with the installation.
Post install scripts
You can create post install scripts for an application. You can create up to three types of post install scripts:
• Post Customer Create Script — A script that executes after customer creation when this application is
part of initial list of applications. It will be executed in the order the applications are installed as part of
customer creation. For example, if you want the new customer's first user to have a custom role instead of
the default Administrator role, you can write a post install script for the Rollbase application that changes
the first user's role to that custom role. See Creating a tenant with no administrative users on page 825 for
details.
• Post App Install Script — A script that executes after the application is installed
• Post App Update Script — A script that executes after the application is updated
To create a post install script for an application:
1. Navigate to the setup page for the application.
2. Click Post Install Scripts.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 127
Chapter 5: Laying the foundation
3. Click Edit next to the type of script you want to create.
4. Edit the script as desired.
Note:
If the post install script's purpose is to create a tenant with no administrator, you can access the automatically
created user with the Administrator role and change the role to a custom role with some administrative
permissions. For example:
var objId = rbv_api.selectNumber
("SELECT id FROM USER where role =90"); // Administrator role's original ID is always
90
var role = rbv_api.stringToJson(rbv_api.getRoleById("868114")); // Custom role with
admin permissions
rbv_api.setFieldValue("USER",objId,"role",role.code); // Set user's role to custom
role
5. Click Save.
Creating and managing objects, fields, and
relationships
If you use the Quick Create wizard to create an application, you can create objects, fields, and relationships
between objects when you create the application. You can also create a new object definition in the context of
an application, or from the list of available objects in setup.
There are two types of objects in an application:
• Core objects will be published and installed with the application, should you decide to distribute it in XML
format. Core objects are explicitly assigned in the application edit page. When you create a new object with
a tab, it becomes a core object by default.
• Dependent objects are pre-requisites for applications: they must be installed prior to installing the application.
Dependent objects can be explicitly assigned in the application edit page as well. However, the system will
automatically add objects as dependent objects to maintain the application's integrity in the following cases:
• The User object is always included as a dependent object for all applications.
• If any core objects have the Approval attribute, the Approval object will be added as a dependent
object.
• Any object associated with a tab which is not included as core.
Topics in this section describe how to work with Rollbase objects, fields, and relationships.
128 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Creating and managing objects, fields, and relationships
Creating a new object definition
To create a new object definition:
1. Launch the What do you want to create? dialog in one of the following ways
• From within an application:
1. On the application menu bar, click +:
2. The What do you want to create? dialog opens.
3. Leave the default selection, A new Object (with Tab), selected and click Create.
• From the list of all objects:
1. From the application switcher, select Setup Home.
2. In the APPLICATIONS SETUP area, click Objects.
Rollbase displays a list of available objects:
3. Click New Object.
The New Object page opens:
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 129
Chapter 5: Laying the foundation
2. Fill in the fields as directed by the explanatory text. Required fields are indicated with a red bar. When you
supply a Singular Name and move out of that field, the other fields are populated automatically with default
values that can be changed. The object definition includes optional properties, attributes, and permissions.
If you do not know which of these you might need, you can come back and add them later.
3. When you are satisfied with the object definition, click Save.
If you leave the box checked to create a new tab, the New Tab screen opens. See Creating a tab on page
130 for more information about creating a new tab for the object definition.
Creating a tab
As part of creating an object definition, you can define a tab. A tab appears in the application menu bar (or as
a child to a tab in the application menu bar) for any selected application.
When you finish creating an object definition, the New Tab screen opens:
130 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Creating and managing objects, fields, and relationships
1. Edit the Properties for the tab:
• Tab Name — The label that appears on the tab. By default, it is the the plural name of the object.
• Description — An optional description
• Parent Tab — If a parent tab is selected the new tab will not appear in the application menu bar. Instead,
it will be available from the drop-down menu of the parent tab.
• Show In — Specifies whether this tab is displayed on desktops, tablets, and/or smart phones. Displays
on all devices by default. Deselect a device type if you do not want the tab displayed on it. Device type
icons appear in the following order: desktop, tablet, smart phone. The Tabs section of the Setup
Application screen contains a Show In column that displays the device types in which each tab appears:
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 131
Chapter 5: Laying the foundation
2. In the Add to Applications section, select the applications to which you want to add this tab.
3. In the permissions table, select the roles and users you want to be able to view this tab.
4. Click Save.
Viewing and editing an Object Definition
View an object definition in either of the following ways:
• In any application in which the object is used:
1. Open the Page Options menu:
2. Select Object Definition.
Note: Object Definition is accessible from all application pages. However, it is not accessible from the
Quick Create and Selector pages, which will not have the Page Options icon.
• Navigate to the list of all objects:
132 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Creating and managing objects, fields, and relationships
1. From the application switcher, select Setup Home.
2. In the APPLICATIONS SETUP section, click Objects.
3. Find the object you want to view and click its name.
The object definition opens:
The controls on the object view page provide the following functionality:
• The shaded ribbon at the top contains links to subcomponent sections, where you can create, edit, or delete
object subcomponents, such as Fields, Relationships, and Pages.
• The Edit button takes you to a screen where you can edit the following:
• Deployment status
• Object properties and attributes
• Permissions
• The Delete button allows you delete this object definition, but the object must first be undeployed.
• The More actions menu allows you to do the following:
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 133
Chapter 5: Laying the foundation
• Clone
• Run triggers
• Add a condition to the object
Adding fields
This topic describes how to create a field from the object definition. You can also create basic fields using the
page editor. Create advanced field types or portal fields from the object definition, as shown here.
For performance reasons, the number of certain types of fields that you can add to a particular object is limited
by Rollbase. Private Cloud users can control these limits as described in Adding columns to a Private Cloud
database on page 835
To add a field to an object definition, navigate to the Fields section and click New Field or New Formula Field.
Choose the most appropriate field type based on the kind of data you want to store in that field. For example,
for a field that will store prices, you might select currency; for a description field, you might select a text area.
Click Next to define properties. The most basic property is the label that is used as an identifier in all pages,
views, reports and any other places the field appears in your application.
As shown in the screen below, some attributes are common to all fields:
• Field Label (mandatory) is displayed on the left from the field on view, edit, and new record pages.
• View Header (optional) is used in headers of views and reports. If not specified, the Field Label is used.
• View Width (optional) is used to set width (in pixels or %) of columns in views and reports. If not specified,
the browser calculates the width of columns automatically.
Each field has a varying number of additional properties based on its type. For example, currency fields have
a size and a currency format property that allows you to select the type of currency to use. Text areas have a
default height and width, as well as a property specifying whether or not to use a rich text editor.
Each field has a set of advanced properties. Different advanced properties are available depending on the type
of the field. For example, all text-based fields can be indexed as part of the full text search engine, but image
fields cannot. Most fields can be audited so you can keep a historical log of when a field has changed its value,
but text area fields cannot be audited. See Field types on page 1302 for information about properties specific to
each type of field.
134 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Creating and managing objects, fields, and relationships
After you have defined properties, you will also need to ensure that each field has a unique integration name.
Rollbase suggests a name based on the label you entered earlier. The integration name is used to reference
this field via merge fields or with Rollbase APIs.
The Field-Level Help box allows you to define help text for the field that will appear in a popup when the user
clicks the help icon next to the field.
After you save the properties, choose the pages and views should include the field. The screen displays a list
of application pages on the left, a list of portal pages in the center (the example shown below does not have
portal pages) and a list of views on the right. Check all that apply.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 135
Chapter 5: Laying the foundation
Field Integration Name
Each field has a unique Integration Name that is used by formulas, templates, and Rollbase APIs. This name
must be unique across all fields in an object definition. When you create a new field, Rollbase automatically
assigns an Integration Name derived from the display label; you can change it at any time. Integration names
for system fields and automatically created fields cannot be changed. Progress recommends using a naming
convention for fields. Changing the Integration Name will affect all existing templates, formulas and integrations
that use that field.
A field Integration Name must conform to the following rules:
• Cannot be more than 20 characters long.
• Must start with a letter.
• Cannot include space ‘ ‘ or pound ‘#' characters.
• Must be unique (case-insensitive) across other field integration names in the same object.
• Must not be one of the reserved system integration names:
startdate, duedate, act, id, id2, ids, srcid, destid, objdefid, cloneid,
returned, view, actionid, relid, relatedid, gridid, gridrows, griddeleted,
country, state, priority, commtype, category, isactive, Fieldname, tag
Configuring Date and Date/Time field formats
Rollbase uses the date and date-time formats you specify on the My Localization Settings on page 715 to format
Date and Date/Time fields. On that page, you specify both a regular format and a long format for date and
date/time. You can control whether Rollbase uses the regular format or the long format when creating or editing
a Date or Date/Time field. Select the property Display full text date value rather than abbreviation to use
the long date or date/time format. Deselect the property to use the regular date or date/time format.
Configuring Integer and Decimal field formats
Rollbase uses the number format you specify on the My Localization Settings on page 715 to format Decimal
and Integer fields on application pages.
For Decimal fields, you can also set the number of decimal places in the Decimal Places property of the field.
For Integer fields, Rollbase uses the number format on New and Edit pages. To use the number format on all
application pages, select Enable Grouping when creating or editing the field.
If you want to disable the numeric formats selected on the My Localization Settings on page 715 for a specific
Integer field, deselect the Enable Grouping check box on that Integer field. This will turn off any formatting for
the Integer field. The selected numeric formatting will be only apply to Decimal fields and to Integer fields that
have Enable Grouping selected.
Enabling field-level help
Field-level help provides a popup window to help end-users. You can implement field-level help per application
as follows:
136 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Creating and managing objects, fields, and relationships
1. Navigate to the application settings, and edit the application definition to set the Enable field-level help
for this application property.
2. Enter help text in the Field-Level Help box. You can use HTML tags to format the text, such as <br/> to
control line breaks.
On object pages, a ? icon displays next to fields for which help has been defined. Roll your cursor over the
icon or click it to display the help text.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 137
Chapter 5: Laying the foundation
Field actions
The Fields section of an object definition has an Action column that allows you to perform different actions
on the field, depending on its type. As shown in the example below, all fields have Edit and Permissions links.
This section covers available actions.
Cloning fields
You can clone all fields except those created automatically by Rollbase, such as the record name. When cloning
a field, you have the option of adding the cloned field to a different object definition. Properties of original field
(including permissions, validation script, and DOM event handlers) will be copied to a new field.
138 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Creating and managing objects, fields, and relationships
Deleting fields
You can delete any field except for system fields created automatically by Rollbase. Fields created by Rollbase
when you enable object attributes and relationships will be deleted automatically if you remove the attribute or
delete the relationship.
For fields you delete manually, when you confirm deletion, the system will:
• Delete the field definition from the object definition.
• Delete all of that field's data for all existing records.
• Remove the field from all pages, views and reports.
The system will not modify formulas, templates, integration links and API calls containing a reference to the
deleted field. It is your responsibility as the application developer to ensure that a deleted field is no longer
used in these components.
Replacing a picklist value
If you need to change a value in a picklist, do not directly edit that value in the picklist field. If you do so, Rollbase
will delete the old value and create a new value. In this case, existing records that use the old value lose the
value in that field. To preserve existing values, use the Replace action as follows:
1. In the Fields section of the object definition, click Replace.
The Replace Picklist Value dialog opens.
2. On the Replace Picklist Value dialog, select the value to replace and enter the new value. This will replace
the old value in all existing records with the new value you define.
3. Click Save.
Converting field types
In the course of application development, you may want to change the type of a field you have already created.
Some fields do allow you to change the data type at any time, as listed below:
• Text fields can be converted into email, picklist, radio buttons, text area, or URL fields. When a text field is
converted into a picklist or radio buttons, Rollbase will:
• Analyze the value of the text field for each record of that object type.
• Create values for all unique values found in the text field.
• Replace original text values with pointers to the newly created values.
• Currency fields can be converted to decimal or integer fields.
• Date fields can be converted to date/time fields.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 139
Chapter 5: Laying the foundation
• Date/time fields can be converted to date fields.
• Decimal fields can be converted to currency, percent, integer, or text fields.
• Email fields can be converted to text or text area fields.
• Integer fields can be converted to currency, decimal, percent, or text fields.
• Percent fields can be converted to decimal, integer, or text fields.
• Picklist fields can be converted into multi-select picklist fields, radio buttons, or groups of checkboxes.
• Multi-select picklist fields can be converted into groups of checkboxes.
• Radio buttons can be converted into picklist fields, multi-select picklists, or Groups of checkboxes.
• Groups of checkboxes can be converted into multi-select picklist fields.
• URL Fields can be converted to text area or text fields.
• Auto-number fields can be converted to text area or text fields.
• Formula fields can be converted to expression fields.
• Expressions fields can be converted to formula fields.
Field level permissions
You can restrict access to a particular field to certain user roles by hiding it completely (uncheck the View
check box) or by disallowing the editing of field values (check the Read Only check box). If set, these restrictions
will be applied on top of Rollbase permissions as described in Access control on page 647.
See Setting field-level permissions on page 659 for more information.
Field validation
On most field types you can define your own server-side validation logic by writing custom JavaScript that
makes use of record-level field values, as well as related field values, to return custom error messages if
required conditions are not met.
To define custom validation, enter a JavaScript expression in the text area. After your users submit data to the
server, this expression will be evaluated. If that evaluation yields a string value, that value will be considered
an error message and the user will be returned back to the data entry page with the error message displayed
(all form data will be preserved).
For example, the following validation ensures that the value of an amount charged field is no more than 100
less than the value of a total due field:
if ({!total_due}>{!amount_charged}+100) {
return "The amount charged is too small. Please make sure the amount charged is no
more than 100 less than the total due.";
}
In some situations when a record is edited, you may want to access the value of a field before it was updated
by the user, as well as the value after it was updated. To do this, use the #before suffix in the merge field.
For example:
if ({!balance#before}-{!balance}<100) {
return "The balance change is too large. Please make sure the new balance is no more
than 100 less than the initial balance.";
}
140 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Creating and managing objects, fields, and relationships
When the user is saving data (for a new or an existing record) and the validation formula returns an error
message, the saving process cannot continue: the user is redirected back to the new or edit page and an error
message is displayed below the field.
This behavior changes if you select the option Treat this Validation Rule as a Warning. In this case, at runtime
the user can select the Ignore Warning box and proceed with saving despite of the warning.
JavaScript event handlers
Field-level events allow you to define custom JavaScript code that executes when a DOM event is invoked.
You can attach JavaScript to any of the following DOM events for a field: onchange, onclick, onfocus, onblur,
onmousedown, onmouseup, onmouseover and onmouseout.
By calling JavaScript functions defined in your pages or in hosted JavaScript code libraries, you can use
field-level events to create a variety of dynamic page behavior. In addition, you can use the Rollbase AJAX
API to add a further level of dynamism to your pages. For more information about client-side scripting in
Rollbase, see Programmatic client-side customization on page 507.
Adding fields to pages, views, and reports
Any time you create a new field, a dialog will prompt for the pages and views on which to add the field. You
can add or remove existing fields from object pages or create new fields with the page editor. You can also
edit views and reports to add, move, or remove fields from appearing in them. See Editing pages on page 369
for more information.
Deleting an object definition
To delete an object definition, you must first un-deploy it by un-checking the Deployed setting. Note that deleting
an object definition also deletes:
• All records of this object type.
• All associated sub components, including fields, pages, and templates.
• All associated menus.
• All relationships with other objects.
Warning: You cannot undo the deletion of an object definition.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 141
Chapter 5: Laying the foundation
Views
A view is a result set, a list of records that users can act on individually or in bulk. When you create an object
definition, Rollbase creates a list view of all records of that object type. You can create additional views and
apply filters to them to present a different result set. Each object definition can have any number of associated
views. The view component in the object definition specifies the fields in the view and the order in which they
appear. Most columns are sortable, depending on their type. Usually the record name column is included in a
view so that users can click the name to view record details. See Working with views on page 437 for details.
The total number of records in a list view is based on the permissions granted to the viewer. In complex cases,
such as when the Location, Department, and Function permissions model is enabled, the number of records
is not shown to avoid overextending resources. Users can also apply and remove temporary filters. See a
sample view and the default set of controls.
To create or modify a view:
• Specify fields, their order, row colors, and filter criteria in the object definition view component.
• Specify the controls available to end users and other page characteristics in the view page.
View controls
When viewing a record list page, you can perform several actions on the view header. The following screen
shows a list view of all Room records:
142 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Views
The view selector allows you to select or create views:
The view header contains the following controls:
• Select menu with the following options:
• New button for creating a new record. By default, this button is available to users with the appropriate
permissions.
• + button, which launches the object's quick create page. You can edit the object's quick create page to
specify which fields display.
• Delete button, which displays for users with delete permission and is active when one or more records are
selected.
• Filter opens a section that allows you to dynamically add filters to select records from the view without
changing the view itself. See Dynamic filtering on page 451 for more information.
• Export menu with the options shown below. The Google option opens the currently selected view in a
Google Docs spreadsheet. Note that your Google account must be set up in your personal settings to export
to Google.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 143
Chapter 5: Laying the foundation
• Delete allows you to move all of the currently selected records to the Recycle Bin. Administrators can
recover records from the Recycle Bin if they are deleted by mistake.
• The group actions menu works with selected records:
The items in the menu vary depending on the object definition and can include:
• Tag, not shown above, for objects with tags enabled, allows you to add keywords to selected records
so you can easily find them in the future. See Tagging records on page 179 for more information.
• Send To allows you to email the selected records.
• Compare allows you to compare the selected records. See Comparing and merging records on page
165.
• Merge allows you to merge the selected records. See Comparing and merging records on page 165.
• Convert allows you to convert the records to a different type. See Converting records on page 160.
• Find Duplicates allows you to find duplicates. See Finding and merging duplicates on page 167.
• Transfer Owners allows you to transfer owners. See Transferring owners on page 173
• Workflow actions, displays for objects with workflow enabled. See Workflow actions on page 266.
• Mass Update allows you to perform the same change to multiple records. Updating multiple records on
page 174
• The checkbox column in the table of records allows you to select multiple records on which to perform a
group action. Selections will be maintained as you navigate through pages of records. Click a column header
to sort records:
144 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Views
• The Columns menu allows you to select which columns display in the view:
Editing a view component
To edit a view component from an application, navigate to the object definition:
1. Open the Page Options menu.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 145
Chapter 5: Laying the foundation
2. Select Object Definition.
The object definition opens. A ribbon of components displays at the top of the page:
Note: Object Definition is accessible from all application pages.
3. Click Views.
The page scrolls to the Views section:
4. Create or edit the view of interest.
5. Click Save.
Setting the default view on a record list page
Control the default view users see on a record list page as follows:
1. From within an application, navigate to the record list page.
2. open the Page Options menu and select Design This Page.
146 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Views
The page editor opens.
3. Click the menu to the right of the view component to open its Properties menu:
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 147
Chapter 5: Laying the foundation
4. Select a view from the Use List View drop-down.
5. Click Save.
The view you selected is now the default view for the record list page.
Relationships between objects
Object relationships are similar to primary and foreign keys in a database. The relationship definition specifies
cardinality (how many records of one object type can be related to another) and whether the relationship is
required. When you create a relationship between objects, Rollbase automatically creates a lookup field in
each object that provides access to related records. Rollbase also automatically creates a view for related
objects that is added to the appropriate pages for both objects.
148 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Relationships between objects
End users will need to view and, in some cases, create and edit related records. Depending on the cardinality
of the relationship and the permissions granted, the lookup field gives users the ability to view, attach, create,
and remove related records.
By default, lookup fields allow users to select one or more records of the related object by displaying a selector
page in a pop-up window. You can change this behavior by allowing users to select records from a picklist or
you can hide the selector. Hiding the selector is useful for objects that a user cannot edit or on pages where
you do not want them editing related objects. Picklists are limited to showing 1,000 records to avoid display
issues. Use grid controls or record lists for objects where you anticipate exceeding that limit.
Global relationship lookup field properties
In addition to page-level settings defined in the page editor, lookup fields have global properties. You can set
these properties when editing a lookup field from an object definition:
• Links Alignment — Choose how links should be aligned on view pages and in views: Horizontal (default)
or Vertical.
• Hide "Quick Create" button for this field — Check this box if you want to hide the button used to create
and select a new related record rather than choosing an existing one.
Note that the Quick Create button is not available (regardless of the global setting) in the following cases:
• If the user does not have permissions to create a new record of the related type
• In pop-up pages, such as Print Preview, and in portal pages
• In Quick Create pages
• For relationships with 1-1 or N-1 cardinality where the related record is already selected
• Main Lookup and Link Lookup — Limits the available choices for this (link) lookup field to be consistent
with the current selection in another (main) lookup field. See Restricting records for lookup fields on page
152 for more information.
• Autocomplete Field — Select the field to be used to find matches when users start typing in the lookup
field. After you type three characters, Rollbase starts displaying matches automatically for the user to select
as desired.
• Autocomplete Rule: Select Starts With or Contains to change the matching behavior of the autocomplete
feature.
• Default Value — Optionally select a record to be selected in this field by default when users create new
records.
• Track all changes to this field in each record's Audit Trail for a complete historical log — Check this
property to automatically add a record-level audit trail entry whenever the field is updated. This option is
only available if the parent object has Audit Trail property. See Auditing on page 169 for more information.
• Always require a value in this field in order to save a record — Check this property if you want the field
to be required.
Changing lookup field behavior
Page lookup field properties allow you to change behavior such as whether a lookup field displays as a pop-up
selector, a picklist, or is hidden. Follow these steps to change lookup field properties:
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 149
Chapter 5: Laying the foundation
1. Navigate to the page containing the lookup field you want to modify.
2. Click the tools icon to display the Page Options menu.
3. Select Design This Page to open the page editor. The following example page has two lookup fields, each
identified by a magnifying icon, Titles and Library Members.
4. Open the Properties menu to the right of the lookup field name:
150 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Relationships between objects
5. From the Style picklist, select one of the following:
• Selector — Users will be able to select related records using a pop-up window.
• Picklist — The field will contain the helper text Please Select. When a user clicks the field, a picklist
displays available related records. For 1-many or many-many relationships, the user can select multiple
records.
• Hidden — The field will not show on this page.
6. From the Use List View picklist, select the view to be used for the selector or picklist. By selecting a filtered
view, you can restrict the records available to end users.
7. Set the remaining properties as follows:
• Use Record in Scope for New Objects — Select to pre-populate the lookup field with the last record
of the type the user was viewing or editing. This is the only option to populate hidden lookup fields.
• Show Record in Scope — Select to display the last record of the type the user was viewing or editing.
8. Click Save.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 151
Chapter 5: Laying the foundation
Restricting records for lookup fields
For certain configurations of relationships, you can restrict the available records for a lookup field based on
other related records using the Main Lookup and Link Lookup properties of a lookup field. These properties
are only available when an object has relationships to at least two objects that are also related to each other.
For example, suppose your application has Country, State, and Company objects with the following relationships:
• The relationship between Country and State is one-to-many.
• The relationship between Country and Company is one-to-many.
• The relationship between State and Company is one-to-many.
If a company has a related country, the states available to that company should be restricted to that country's
states. You can enforce that restriction using the Main Lookup and Link Lookup properties of the lookup field
that represents the relationship from Company to State.
In this example, the Company object's lookup field State has the following properties:
The Main Lookup property specifies that the company's related country limits the choices for the lookup field.
The Link Lookup property specifies that the State lookup field will be restricted to the country's related states.
The following example illustrates how the Company's State lookup field is restricted.
The application contains two countries:
152 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Relationships between objects
The country Canada has four states:
The country United States has five states:
After setting a company's country, its State lookup field is filtered to show only that country's states:
You can also restrict the records for a lookup field using the client-side API rbf_setLookupFilter() on page 1106.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 153
Chapter 5: Laying the foundation
Related records components
Related records components are used to display a list of related records for objects with 1-many or many-many
relationships. For example, if you have an room object with a one-to-many relationship with furnishings, the
room view page can contain a related record component:
Related record components are only shown on view pages for specific records and automatically filter the data
displayed to only show those records that are related to the current record being viewed.
You can use the page editor to define whether or not you want to hide or show controls of the related record
component such as Quick Create and New. See Editing pages on page 369 for more information. You can also
use the page editor to define which view should be shown by default. For more information on creating and
configuring views, see Views on page 142.
Related grid controls
While related records show up on object view pages, grid controls can be used to edit, create, or delete related
records inline on new and edit pages. This feature is particularly useful for building master-detail input, such
as a quote with quote line Items, invoices, purchase orders, time, etc. Grid controls are useful for any situation
in which you need an arbitrary number of line items all editable on the same page.
154 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Relationships between objects
For example, the following screen shows a grid control from a room reservation system:
When adding and configuring a grid control on a new or edit page, you can define the fields shown in each
row, and you can attach custom JavaScript event handling code for performing calculations and other operations
when fields are updated or rows are added and deleted.
For more information on setting up and configuring grid controls, see Using grid controls to manage multiple
records on page 383.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 155
Chapter 5: Laying the foundation
Orphan records
The Orphan Records Control section of a relationship allows you to specify whether or not related records
get deleted when the parent record is deleted. For example, if a user deletes a quote record, it might make
sense to delete all of the related line item records. But the opposite case is not true; if a user deletes a line
item, it does not make sense to delete the related quote record. Edit the relationship component in the object
definition to change this behavior.
Working with records
Rollbase provides controls for cloning, merging, and converting records, among other actions. You can control
which actions are available for users by setting permissions and editing pages. Topics in this section describe
how to perform actions from the toolbar group actions menu shown below. Note that some menu options, such
as Tag, are only available if their associated property or attribute is enabled in the object definition.
The following topics describe how to work with records:
• Cloning records on page 157
• Protecting records on page 159
• Converting records on page 160
• Finding and merging duplicates on page 167
• Auditing on page 169
• Sending email on page 171
• Transferring owners on page 173
• Updating multiple records on page 174
156 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Working with records
• Tagging records on page 179
Cloning records
When you clone a record, the new record page opens with all fields prepopulated with values from the original
record. You can change field values or accept those from the original record. The original record is not affected
when you create a cloned record. For some objects, it makes sense to clone related records when cloning a
record. For example, when cloning a Purchase Order record that has relationships with Line Item records, it
makes sense to clone all of its related line items. The following illustration shows a parent record with related
records and shows how a cloned record can include cloned related records.
As the following screen shows, the object definition relationship component provides controls for cloning related
records. In the example shown from a corporate room reservation system, when a new room becomes available
it might be configured with a certain set of devices such as a projector, coffee maker, and whiteboard. When
the user clones a particular room record, they want it to be populated with this set of devices. To enable that,
you would check the second box, Clone all related Devices when any Room record is cloned.
With a Clone all related… flag checked, related records are cloned and attached to the resulting cloned
records. If the new record page for an object contains a grid control and Clone all related… is checked, the
grid control will be automatically pre-populated with information corresponding to the original related records.
As an alternative to the cloning mechanism, in the new record page you can use the lookup fields to attach
existing related records. If the new record page for the object has a lookup field configured to explicitly select
related records, this supersedes the Cloning Control settings in the relationship definition.
How to clone records and set cloning behavior for related records
Initiate and set cloning behavior as follows:
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 157
Chapter 5: Laying the foundation
• When viewing a record, clone it by selecting Clone from the action menu:
• To edit the cloning setting on a relationship:
1. Navigate to the parent object definition's Relationships section.
2. In the Cloning Control section, select the cloning behavior for each side of the relationship:
158 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Working with records
Protecting records
You can control whether users can modify or delete records with the following mechanisms:
• Setting user permissions as described in Security and access control on page 643.
• Locking individual records as described in Locking records on page 159.
• Creating conditional formulas that remove edit and delete controls as described in Condition formulas to
disable editing and deleting records on page 159.
Locking records
You can lock individual records to prevent users from editing or deleting them. To use this feature, enable the
Lockable attribute in the object definition. Records of that type will have an Is Locked check box. If you enable
the attribute on an existing object definition, you need to edit views and pages, such as the new record page,
to include the new attribute.
The Is Locked checkbox can be set to locked by directly editing a record, or by using a mass update or trigger
— any mechanism that updates records. A new Trigger Type - > Update Field Value with Trigger Name -
> Set Lock is created when you enable the Lockable attribute. To remove locks on multiple records, use a
trigger or an API call to set the Is Locked checkbox to false.
When you lock a record, it has the following effect:
• Edit and delete controls on the record's view page are disabled.
• The Is Locked field displays a closed lock icon.
• Fields for related objects on the record's view page do not display links to create, attach, edit, or delete
related records.
• Edit and delete controls for the locked record on related record view pages are disabled.
Workflow actions are still available when a record is locked. If you want to disable workflow actions on locked
records, add a condition formula to each workflow action you want to disable. The formula returns false if the
record is locked.
To add a condition formula to a workflow action:
1. Navigate to the workflow action from the object definition.
2. Click Edit.
3. In the Action Condition Formula section, enter the following formula:
!{!isLocked}
Condition formulas to disable editing and deleting records
An alternative to locking records is to disable edit and delete functionality based on record values using condition
formulas. You can define condition formulas on an object that return true or false based on record field values.
You can use the same formula to disable edit and delete, or you can use different formulas to disable edit and
delete. If the formula returns false for a particular record, Rollbase disables the controls to edit or delete that
record.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 159
Chapter 5: Laying the foundation
To define condition formulas to disable editing and deleting object records:
1. Navigate to the object definition.
2. From the More actions menu, select Condition Formulas.
3. In the Formula to Enable/Disable "Edit" Functionality section, enter a condition formula to enable or
disable editing records.
4. In the Formula to Enable/Disable "Delete" Functionality section, enter a condition formula to enable or
disable deleting records.
For example, the following formula disables editing (including Inline editing and mass update) for records with
a status code of CC:
"{!status#code}"!="CC"
Condition formulas interact with other features as follows :
• Rollbase applies permissions before a condition formula (see Security and access control on page 643).
• Rollbase applies the locking mechanism before a condition formula (see Locking records on page 159).
• Rollbase does not apply condition formulas defined on objects to workflow actions or to API calls.
Converting records
You can convert records of one type to another type, such as leads to accounts. A conversion map specifies
how the fields in the source record map to those in the target. The source and target objects do not need to
have exactly the same set of fields, but only values in the fields you map will be populated the new record.
You can create a conversion map in the source object definition or in the process of conversion when using
the Convert menu action. To create triggers or workflows that convert objects, a conversion map must be
present in the object definition.
You can only map a field to a field with a compatible type. Rollbase automatically suggests the mapping for
fields with matching names, but you can change them. Fields with default values can be mapped. You can
also map a field to a constant value such as a string, number, or particular record for lookups, or to an expression.
Expressions may include server-side API calls or be simple formulas, such as {!total} - {!amount},
built from source field tokens. See Adding business logic on page 183 for more information.
Picklist fields can be mapped and converted if the following are true:
• The source and target objects have a picklist with the same set of values.
• The source and target picklist items have the same integration codes.
The general steps for creating a conversion map include:
1. Initiate conversion in the context of a record or the object definition of the type of record to convert.
2. Choose the destination object type.
The Conversion Map screen displays mappable source object fields. Read-only fields and template fields
will not be available.
3. From the menu next to each field, select the target field.
4. Choose whether to delete the source object after record values have been converted to the target object
type.
160 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Working with records
Deleted source records will be moved to the Recycle Bin without deleting dependent records. This setting
has no effect if a conversion map is used in workflow action or trigger.
Converting records to a different type
You can initiate conversion of records from one object type to another in the following ways:
• Multiple records:
• By selecting the records in a list view and using the Convert option from the group actions menu.
• Using conversion maps with triggers and workflow actions.
• A single record: By opening its view page and using the Convert option from the group actions menu.
To convert one or more objects from a list view, follow these steps:
1. From the application menu bar, click the object type for the records of interest.
• If the application uses the Traditional UI blueprint, click the object type for the records of interest from
the application menu bar. If you don't see the object of interest, check the overflow menu.
• If the application uses the Modern - Vertical Menus UI blueprint, click the object type for the records of
interest from the sidebar.
2. Select the object(s) to convert:
• To convert all, select All from the select menu:
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 161
Chapter 5: Laying the foundation
• To convert all on a page, select This page from the select menu and check All.
• To convert a subset, check the box next to each record.
3. Open the group actions menu:
4. Select Convert.
A screen opens for you to select the target object type. The following example shows the screen that appears
when converting a title from a sample library application to a check out:
162 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Working with records
5. Select the target object type. Available types include all deployed objects except the source object.
6. Click Next.
The Conversion Map screen opens:
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 163
Chapter 5: Laying the foundation
7. Map the fields as desired. Required fields must be mapped. See Converting records on page 160 for more
information on mapping.
8. Optionally check the box to have the original record deleted after the conversion.
9. Optionally click Save Map to save the conversion map in the source object definition.
After saving, you will be able to convert the records or cancel.
10. Click Convert to convert the selected records.
Attaching cloned related records to converted records
When you convert a record from one object type to another, you can choose to attach cloned related records.
To enable this conversion, when creating a conversion map, check the box in the Clone Matched Related
Objects section.
164 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Working with records
Comparing and merging records
In a list view, the group actions menu offers options for merging, finding duplicates, and comparing records:
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 165
Chapter 5: Laying the foundation
These related options differ as follows:
• Compare allows you to select and view multiple records side-by-side, and offers the option to merge the
records.
Note: The limit for the records compare is 12 records. Upon exceeding this limit, "Too many data objects
to compare" error is encountered.
• Find Duplicates searches for duplicate records based on the values in the fields you select. If duplicates
exist, you will have the option to merge them.
166 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Working with records
• Merge allows you to select values from multiple records and merge them into the record on the left. Rollbase
moves the other record(s) to the Recycle Bin without running any triggers, such as those to be run on delete.
Records dependent on the recycled records will now be dependent on the merged record and are not
deleted.
Refer to these steps for finding and merging duplicates.
Finding and merging duplicates
Select a record to check for duplicates and merge as follows:
1. From the application menu bar, click the object type for the records of interest.
• If the application uses the Traditional UI blueprint, click the object type for the records of interest from
the application menu bar. If you don't see the object of interest, check the overflow menu.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 167
Chapter 5: Laying the foundation
• If the application uses the Modern - Vertical Menus UI blueprint, click the object type for the records of
interest from the sidebar.
2. Select the record to check for duplicates.
3. From the group actions menu, select Find Duplicates.
The Find Duplicates screen opens.
4. Select the field(s) to search for duplicates.
Rollbase will search for records with values that match those in the selected fields.
5. Click Find.
168 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Working with records
6. If records matching the selected criteria are found, select the records to be merged and click Merge.
Rollbase displays values from the records to be merged. The following example shows a record where all
fields were selected and one duplicate was found. The values on the left are from the selected record.
7. From the records shown, select the correct value for each field.
Rollbase merges the records into one record, with the selected values. In the following example, the author's
name and date were incorrect in the first record. By selecting them from the second, the merged record will
have the correct values for all fields.
Auditing
Rollbase automatically tracks some activities, and you can enable additional logging as described below. Audit
trail entries are created automatically for activities such as creating, merging, and converting records. Rollbase
also creates audit trail entries when an administrative user makes changes to an object definition or an
application. The Audit Trail component at the bottom of the object definition or application definition contains
these entries.
The following example shows an application Audit Trail section. Click Show All to view audit trail entries in a
pop-up window, from which you can export a full history of changes.
By default, the System Info section of a record view page contains audit trail entries as shown in the following
screen. You can move the component or remove it by editing the page. The Audit Trail list view component
shows the 20 most recent entries. Use Show All from the Action menu to see up to 100 entries in a pop-up
window. You can also export all entries to XLS or CSV format from this window.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 169
Chapter 5: Laying the foundation
Audit trail records cannot be modified or deleted manually. Rollbase deletes the audit trail only when an
associated tenant is deleted.
You can enable finer-grained auditing in the following ways:
• To track changes made to records, enable Audit Trail property on an object definition. You can selectively
enable tracking of operations like view, edit, and delete.
• When enabled, the Audit Trail property allows Rollbase to track changes to record fields made by API
calls, triggers, and end users. You can enable the Audit Trail attribute during object creation, or for
existing objects, by editing the object definition.
• When an email related to a record is sent. In this case, the View control displays a copy of the email
message that was sent. This audit trail entry is created when the email message is actually sent, typically
with a short delay.
• To track changes for a particular field, in the object definition, edit the field. A field-level audit can be enabled
only when the audit is enabled at the object level.
• To generate custom, template-based audit trail entries, create a workflow trigger of type Create Activity
Trail Record.
Enable auditing for an existing object
To enable an audit trail for an existing object, follow these steps:
1. Open the Page Options menu.
2. Select Object Definition.
The object definition page appears.
Note: Object Definition is accessible from all application pages.
170 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Working with records
3. Click Edit.
4. In the Object Properties section, find the Audit Trail property:
5. Click to enable the audit trail and the desired user actions.
6. Click Save.
Sending email
Rollbase offers various ways to send emails that include record information. You can send single or multiple
emails at one time and you can fill in the body of the email manually or create a template to fill in details ahead
of time.
Merge tokens allow you to specify values that Rollbase replaces with literal values when sending the emails.
This sample template body in a room reservation system uses tokens for the reservation start time and the
room name:
Your reservation starting at {!start_time} for {!R791988.name#text} has been
confirmed. The resulting email looks something like this:
Your reservation starting at 08/25/2015, 11:00 AM for Atrium Social Corner has
been confirmed.
To send an email, click Send To from the group actions menu on a records list page when you have one or
more records selected:
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 171
Chapter 5: Laying the foundation
The following example shows the Send an Email screen that opens when three records were selected from
a list view. An email message is sent for each selected record:
To change the address in the From line in Rollbase-generated email messages, open the account settings
page and change the value for Default Email Sender. For information about advanced setup and administration,
see Advanced setup and administration on page 713.
The screen contains the following fields:
• In the Send Email section:
• The first line lists the record(s) whose information will be used for the emails. In the example above,
reservations made by Sandy Beauchamp and Adams.
• Reply To — The address to which replies to this email will be sent. Either the current user's email
address, noreply, or the Default Email Sender address specified in Setup > Administration Settings
> Account Settings.
• Send To — The address email(s) will be sent to. If the record contains an email address, selecting
Record's Address will use that address. Objects with the Contact attribute enabled have an email field
and you can add email fields to object definitions as well. The Specified Address radio control allows
you to enter email addresses manually. A new section opens with fields to enter addresses or merge
tokens for To, CC, and BCC. You can enter several addresses separated by space, comma, or semicolon.
You can use template tokens for formula fields of String type which return one or more valid email
addresses in "To", "CC" and "BCC" Fields. For information about using templates and formulas, see
Adding business logic on page 183.
• Do not send duplicate emails to the same address — Ensures that Rollbase only sends one email
to each address. Selected by default. If you want multiple emails sent to one address, deselect this check
172 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Working with records
box. For example, if you select multiple records and want to send and email for each record to the same
email address, deselect this check box. If the check box is selected in this case, Rollbase only sends
one email associated with the first selected record.
• In the Email Template section:
• The first field allows you to select a predefined email template. Email templates are components in the
object definition; see Email templates on page 199 for more information. If you select a template, the
remaining fields are filled in automatically as specified in the template. If you do not select a template,
you can manually fill in the email.
• Format — Format options of Plain Text or HTML.
• Subject — The email's subject line. A value will be filled in automatically if you selected a template. You
can change or enter a subject.
Transferring owners
If an object has a relationship with the built-in User object, records can be associated with a particular user.
Click Transfer Owners in the group actions menu to quickly change the ownership of the selected records
from one user to another. This option is only available if the object definition has at least one relationship with
the User object.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 173
Chapter 5: Laying the foundation
Updating multiple records
The Mass Update group actions menu option allows you to specify values that will be applied to all selected
records. Rollbase creates a default Mass Update page that displays when a user selects this option. The
default page exposes no fields. You can edit the page to add and remove fields by selecting Design this Page
from the Page Options menu. If you add a field to an existing object, you have the option of including it on the
Mass Update page (among others). If a Mass Update page has multiple fields, only those in which a user
enters values will be updated.
If you add a lookup field for a related object in a Mass Update page, the updates follow the rules defined for
the relationship. For example, in a relationship where one device can only be related to one room, if a user
selects that device, it will only be updated in the first record.
174 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Working with records
To support updates of different sets of fields on the same object, you can create multiple pages by cloning the
the Mass Update page in the object definition. When multiple Mass Update pages exist for an object, Rollbase
adds them as an option to the group actions menu. The following screen shows an example of a menu option
for a custom Mass Update Furnishings page that an administrator added to this object definition.
Adding fields to a Mass Update page
To add or remove fields from a Mass Update page, follow these steps:
1. Navigate to the Pages section of the object definition.
2. Locate the Mass Update page.
3. Click Edit.
The page editor opens:
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 175
Chapter 5: Laying the foundation
4. In the left pane, select the fields you want to expose for mass update and drag them to a section in the
page.
You can use the default section, add your own section, or both.
5. When the page contains all of the fields for mass update, click Save.
Cloning a Mass Update page
To clone an existing Mass Update page:
176 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Working with records
1. Navigate to the Pages section of the object definition.
2. Locate the Mass Update page.
3. Click Clone.
The page editor opens.
4. Change the name of the cloned page.
This name displays in the group actions menu.
5. Modify the contents of the page as desired.
6. Click Save.
Making a mass update
To update multiple records at one time:
1. From a list view, select the records to update.
2. From the group actions menu, select the appropriate mass update option.
If an administrator has created multiple Mass Update pages, they will appear on the menu.
3. Choose whether the update trigger should run when you save.
4. Fill in the values for the fields that you want to update. Blank fields will not be updated.
For example, the value in the following screen will cause the selected records to have projector in their
Device field.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 177
Chapter 5: Laying the foundation
5. Save the page.
6. To define the Mass Update page behavior for Lookup fields, do the following:
a) Open a Mass Update page with any Lookup field. The default mode is Add to existing value. This
behavior means that when you select another item from the Lookup field selector, the new value gets
added to the existing value(s).
b) To overwrite existing values of a Lookup field, select Page Options > Design this Page.
178 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Working with records
c) Hover over the Lookup field to view and click its associated drop-drown icon. The Properties pop-up
appears.
d) Select the Overwrite existing values checkbox and close the pop-up.
7. Save the Mass Update page. The Lookup field now shows label as Overwrite existing values. When you
select another item from the Lookup field selector, the existing value is overwritten and replaced with the
new value(s)
Tagging records
A tag is a label used to describe one or more records. Records tagged with keywords show up as matches for
searches on any of those keywords. In addition, when you view a record with tags, you will be able to see all
the tags affixed to that record, along with how many different users tagged that record with the same keywords.
Clicking a tag automatically performs a global text search for that keyword and displays the search results.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 179
Chapter 5: Laying the foundation
Tags must be enabled per object by selecting Show "Tag" Option in the Optional Object Properties section
of the object definition:
To add tags to records from a list view:
1. Select the records to tag.
2. From the group actions menu, select Tag:
The Tag dialog opens:
180 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Working with records
3. Enter the tags separated by commas and click Save.
Record Validation
For a new or existing records, the record validation feature validates the user input in the fields, wherever
applicable. In the event of validation failure, Rollbase indicates and displays the number of errors associated
with tab(s). This helps the user to easily identify and fix the errors resulting in improving the error recovery time.
When a validation error occurs for a new or an existing record, the data is not saved, and an error message
appears.
Here's an example of how an error appears:
• Errors are homogeneously segregated based on the record information. The tab header displays the error
count along with an error icon.
• In case of an input field, the error displays an associated validation criteria. This helps a user to provide
values in the correct format.
If errors exist:
• For a specific tab of a record - the corresponding tab is highlighted.
• In any tab of a multi-tabbed record - the first tab with error is highlighted.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 181
Chapter 5: Laying the foundation
182 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
6
Adding business logic
After an application contains the appropriate objects and relationships to capture data, you will likely want to
add logic that uses or transforms that data. Rollbase supports this through templates and formulas. Templates
allow you to define a structure for calculating and displaying information. Templates contain tokens, which are
variables that the runtime replaces with values from the object currently in scope. Formulas are interpreted as
Javascript expressions, they describe how to calculate values. If a template contains formulas, the runtime first
parses the merge tokens to obtain the values. Once the values are obtained, the runtime evaluates the Javascript
expressions using the appropriate values.
For example, suppose an object contains fields for quantity and price and you want to calculate the price of a
particular quantity. Using the tokens, {!quantity} and {!price}, which correspond to fields in the relevant
object, the runtime will handle them in a formula as follows:
• Formula: {!quantity} * {!price}>
• Parsed formula values evaluated as Javascript: 100.0 * 5
• Result: 500
The following table describes the areas of a Rollbase application where you can use templates and formulas
and why you might use them.
Templates Where and How Used Formulas Where and How Used
Page HTML and Script Create in page editor Object formula fields Object definition
components
Object template fields and Create in Object definition Trigger conditions and Part of trigger definition
integration links expressions that determines when
trigger will run or what
value to use as a result
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 183
Chapter 6: Adding business logic
Templates Where and How Used Formulas Where and How Used
Object Record Name Object definition to Workflow action conditions Part of workflow definition
Template automatically generate that determines whether
record names workflow should proceed
Mail Templates Object and workflow Field validation conditions Object field definition
definitions to dynamically
generate e-mails
Document Templates Workflows, Values calculated in Part of gauge definition to
template-based reports, gauges calculate values to render
and Document Template in the gauge
fields to dynamically
generate documents
Report Templates Report definition to EVAL blocks In non-formula templates,
dynamically generate such as email or
reports document, use to embed
a formula
For details, see the following topics:
• Working with templates
• Formulas
• Triggers and workflows
• Workflow processes
• Workflow overview
• Automating business decisions with Corticon rules
• Reports, charts, and gauges
• Multi-currency support
• Surveys and quizzes
Working with templates
Topics in this section describe how to work with templates.
184 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Working with templates
See the following topics:
• HTML and Script components on page 185
• Adding template fields and integration links to an object on page 188
• Creating a record name template on page 198
• Creating and using string tokens on page 193
• Template token syntax on page 188
• Iterating through records on page 196
• Using EVAL blocks on page 198
• Email templates on page 199
• Document templates on page 201
• Communication logs on page 206
• Localization on page 206
• New record template on page 206
• Right to left support in templates on page 207
HTML and Script components
HTML and Script components allow you to add templates and formulas to a page. The HTML will be rendered
when the user views a page. Script components can perform calculations and handle events using JavaScript.
Adding business logic on page 183 introduces where templates and formulas can be used in a Rollbase
application.
HTML components
HTML components allow you to customize the way a page displays. You can use them on application or portal
pages. You can add formatting with stylesheets and HTML code. The Template Helper makes it easy to add
data elements, perform calculations, or call Rollbase APIs to perform functions. You can also use string tokens
in HTML components. See Creating and using string tokens on page 193 for information about custom string
tokens. To add Javascript formulas to an HTML component, insert them in <script> elements.
As a simple example, suppose you want to provide a greeting to the current end user on an application page.
You can simply add an HTML component to the page and use a token to retrieve the name. The following
shows how to use the Template Helper to find the token for selecting the current user and filling in the first
name:
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 185
Chapter 6: Adding business logic
With the user Adam Ministrator logged in, Rollbase renders this template as follows:
Script components
Script components can perform calculations and handle events using JavaScript. You can also use string
tokens One use of a script component is to customize page content when the page is loaded. For example,
suppose you want to hide a field and its label when the page is loaded. The following script shows how to
structure an event handler in a script component, in this case, an event handler for the
rb.newui.util.customEvents.rbs_pageRender event, which occurs when a page is loaded using an
AJAX request, the response to the request has been received and rendered.
<script>
rb.newui.util.addEventListener(rb.newui.util.customEvents.rbs_pageRender,function(){
console.log('page is rendered');
rbf_showOrHideField("Checkbox",false);
});
186 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Working with templates
</script>
Adding an HTML component to a page
To add an HTML component, to a page, follow these steps:
1. Navigate to the page you want to edit and click Design This Page to open the page editor.
2. If the page does not contain a section to hold an HTML component, drag a New Section component from
the left pane onto the page.
3. In the left pane, select New HTML Component and drag and drop it on the page on the right pane.
4. If the tenant supports multiple languages, you can create content in each language by selecting the language
from the drop-down menu. See Translating application component names and labels on page 746 for more
information.
5. Click Edit to display the Edit HTML page.
6. In the text box below the formatting bar, create the template for your page.
7. Use the Template Helper area of the editor to insert tokens that select values:
a) From the left drop-down menu, select the type that you want to retrieve values from.
b) From the second drop-down, select the field value of interest to display the token required to extract that
value.
c) From the field below the drop-downs, select the token value and paste it in the template body.
8. Click Save to save the template and return to the page editor.
9. Save the page.
Adding a script component to a page
Script components allow you to add Javascript formulas to a page. Adding business logic on page 183 introduces
templates and formulas.
1. Navigate to the page you want to edit and click Design This Page to open the Page Editor.
2. If the page does not contain a section to hold a script component, drag a New Section component from
the left pane onto the page.
3. Add a script component by dragging and dropping it on the page.
4. Click Edit to display the Edit Script page.
5. Insert the script for your page.
6. Use the Template Helper area of the editor to insert tokens that select values:
a) From the left drop-down menu, select the type that you want to retrieve values from.
b) From the second drop-down, select the field value of interest to display the token required to extract that
value.
c) From the field below the drop-downs, select the token value and paste it in the template body.
7. Click Save to save the template and return to the page.
8. Save the page.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 187
Chapter 6: Adding business logic
Adding template fields and integration links to an object
Template fields are similar to template-based HTML components, but can be used in views and page layouts
because they are part of an object definition. Integration links require URL encoding. The Rollbase template
engine automatically selects the correct encoding rule, but you must enter URLs using the correct syntax. You
can use template fields in combination with other field types to deeply customize the Rollbase user interface
(see the example below).
Template fields have an option to hide the display label that is normally shown on the left in pages. This feature
is especially useful for creating a single piece of JavaScript code to be added to multiple pages.
1. In an Object definition page, scroll down to the Fields section, click New Field and select Template or
Integration link as the Field type.
2. If you chose Template, enter HTML for the field's body and embed any Template merge tokens as needed
using the merge field helper.
3. If you chose Integration link, enter link URL.
4. Preview the resulting field by clicking the Preview Template or Preview Link link.
In this example, a related field on the Order object points to the email address of a related user. This
related field will display a link to send an email to that user. To add a link to send an email using Order
fields to a different related email address, create a template field with the following HTML Template:
<a href='../m/send.jsp?act=clean&id={!id}&
objDefId={!#OBJ_ID.order}&to={!relatedEmail}'>{!relatedEmail}</a>
This template will render a link to a Send Email page using fields from the current Order record, and
the email address from the related field.
Template token syntax
Rollbase provides a set of built-in tokens, and you can create string tokens for your own use. The Template
Helper allows you to find and copy available tokens. Using the Template Helper helps you avoid issues from
typos. However, you may find it beneficial to learn token syntax for troubleshooting other issues. Generally, a
token has a form similar to:
{![Prefix].TokenName#[Suffix]}
• Prefix (optional) is the integration name for the relationship, if any. For example: R123456. For hierarchical
relationships, it additionally includes #C for the child side of the relationship and #P for parent side of the
relationship.
• TokenName (mandatory) represents the integration name of the field.
• Suffix (optional) includes additional instructions on how to render a given token.
If you do not specify a suffix, the field is rendered as HTML for HTML templates and plain text for text
templates. For example, in HTML templates, a checkbox will be rendered as an image (a checked or
unchecked box) and an object's name field will be represented by a link to a record view page.
If you create custom string tokens, the syntax is {!#token_name#}. See Creating and using string tokens
on page 193 for more information.
188 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Working with templates
Several unique tokens can be used to build links within template components (use actual object integration
name instead of objName). For example, a URL generated by #REPORT token can accept filtering parameters:
• filterName: name of field to filter
• filterValue: value of field (only records with this value will be shown in the report)
Example: {!#REPORT.123456}&filterName=R45678&filterValue={!id}
All fields from the currently logged-in user and current customer are available for use in templates:
• {!#CURR_USER.name}: name of current user
• {!#CURR_CUSTM.name}: name of current customer
You can also use tokens for:
• Company-wide settings (see Using company-wide settings on page 726)
• Current portal user (for portal Pages)
• Shared images (from any Object)
• Helpers
The remaining topics in this section list built-in tokens and describe how to create and use string tokens.
Common tokens
The following tokens are commonly used in templates and formulas:
FIELD TYPE SUFFIX MEANING
Any type #before Field's value before update (for
triggers, see below)
Any text field #url URL-encoded text (for use in URL
templates)
Text field #value Plain text (ignore template-specific
encoding)
Picklist, Status, or Role #id ID of field's value or
comma-separated list of IDs
Picklist, Status, or Role #value String value of field or
comma-separated list of string
values
Picklist, Status, or Role #code Integration code of field's value or
comma-separated list of integration
codes
Text Area #html Raw HTML value (for rich-text text
areas)
Text Area #text HTML-encoded text value
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 189
Chapter 6: Adding business logic
FIELD TYPE SUFFIX MEANING
Lookup #id ID of first related record or -1 if no
related records exist
Reference #id ID of referenced record or -1
Reference #value Object name of referenced record
Record Link (name field) #text Record's name as plain text
Record Link #link Link to View Page (for HTML
Templates)
Record Link #url URL to View page
Checkbox #value "true" or "false"
Decimal, Currency, Percent #value Unformatted number
Date, Date/Time #iso Date or date/time formatted in ISO
8601 format. Example: 2011-10-13T
Date, Date/Time #js Date or date/time formatted in
JavaScript format. Example: Thu
Oct 13 2011 08:06:48 (PDT)
Document Template #id ID of selected Template
Document Template #link Link to file generated from Template
Document Template #url URL to file generated from Template
Email Template #id ID of selected Template
Email Template #link Link to preview email Template
Email Template #url URL to preview email Template
Shared Image #html HTML with IMG tag (for HTML
Templates)
Shared Image #url URL to image
File Upload #html Link to uploaded file
File Upload #url URL to uploaded file
Advanced tokens
The following tokens provide advanced functionality that you can use in templates and formulas. Rollbase
replaces the token with the content described below:
190 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Working with templates
Token Will be replaced with ...
{!#TODAY} Today's date in the user-selected format
{#SESSION_ID} User's session ID
{#PAGE_ID} ID of current page
{!#HOST_NAME} Host name of the server running the Rollbase instance
{!#LINK.objName} Link to the object's view page assigned to current user
{!#LINK.objName#id} ID of the object's view page assigned to current user
{!#LINK.objName#12345} URL to the object's page specified by the original ID
(only available for view, new record, and edit pages
and only if more than one page of each type exists
(e.g. at least two view pages))
{!#LINK.objName#generic} URL to the object's generic page assigned to current
user
{!#LINK.objName#template} URL to the templates page
{!#LINK.objName#import} URL to the object's import page
{!#LINK.objName#search} URL to the object's search page
{!#LINK.123456#tab} URL to the generic or web tab specified by the original
ID
{!#OBJ_ID.objName} Object definition ID for the specified object
{!#CURR_USER.fieldName} Value of the specified fieldName for the currently
logged in user
{!#CURR_CUSTM.fieldName} Value of the specified fieldName for the current
customer
{!#SETTINGS.fieldName} Value of the specified fieldName for Company-wide
Settings
{!#ISV_VALUE.fieldName} ISV customers only: Value of the specified fieldName
for an ISV account. The fields must be marked as
Make this field available for related ISV customers,
see Using the ISV Partner application on page 945
{!#PORTAL. 688851.#id} ID of the portal with the specified original ID
{!#PORTAL.688851.705908#id} ID of the portal page with the specified original ID
{!#PORTAL.688851.705908#url} URL of the portal page with the specified original ID.
This token can be used in the user interface.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 191
Chapter 6: Adding business logic
Token Will be replaced with ...
{!#PORTAL.688851.705908#link} Link to the portal page with the specified original ID
{!#PORTAL.688851.705908#emailUrl } URL of the portal page with the specified original ID.
This token can be used in emails.
{!#PORTAL.688851.logout#url} URL to the logout page for the portal with the specified
original ID
{!#PORTAL.688851.logout#link} Link to the logout page for the portal with specified
original ID
{!#PORTAL.688851.emailUrl} URL to Portal's main page which is safe to use in
emails
{!#REPORT.123456#body} The HTML body of a text-based report with the
specified original ID
{!#REPORT.123456#url} The resource URL that generates the report with the
specified original ID.
Note: This is not available for tabular reports.
{!#REPORT.123456#body? The HTML body of a text-based report filtered by a
fieldName=fieldValue} field value. The fieldName parameter specifies the
integration name of a field by which to filter,
fieldValue specifies the value on which to filter,
such as country=USA.
{!#FILTER} HTML with content of current report filters. For
template-based reports only.
{!#CURR_VISIT.name} Display name of the current portal user
{!#CURR_VISIT.id} ID of the current portal user
{!#CURR_VISIT.loginName} Login name of the current portal user
{!#UID} Unique string ID of objects imported from an external
database or an OpenEdge Service.
192 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Working with templates
Token Will be replaced with ...
{!#CP_TOKEN} A client principal token used to access a JSDO Invoke
method on an OpenEdge Data Object from Rollbase
Object script. This token can be used in an HTTP
header under the header name
X-OE-CLIENT-CONTEXT-ID.
{! #CSRF_TOKEN} Rollbase servlets are now guarded with CSRF tokens
and thus making the platform more secure. Any custom
code that directly hits a Rollbase servlet with POST
call requires CSRF token to be passed in the call. For
details about CSRF, please refer
https://www.owasp.org/index.php/Cross-Site_Request_Forgery_(CSRF)
Creating and using string tokens
You can create your own string tokens. A string token is like a global variable in a programming language; it
evaluates to an actual value at runtime. You can use string tokens in templates and formulas. See Adding
business logic on page 183 for details about where you can use templates and formulas in a Rollbase application.
String tokens are useful for holding text that one or more applications in a tenant use frequently and that is
displayed by code in a template or a formula. For example, you might create a string token and use it to display
a company name. If the company name changes, you only have to change the string token to change it in all
applications in the tenant.
String tokens support values in multiple languages for tenants that support multiple languages. See Language
support on page 740 for information about support for multiple languages. See Creating and using multilingual
string tokens on page 750 for information about storing string token values in multiple languages.
Every string token you create is available to any application in the tenant. You must attach a string token to
any application that uses it before publishing or exporting the application. See Attaching string tokens for details.
The following example walks through the steps to create a string token for a tenant and use the string token
in an HTML component on a page.
To create a string token:
1. Navigate to a location where you can edit a template or formula.
2. From the Template Helper, click String Tokens.
3. Click Add.
4. Enter the string token value and a Token Name. The following screen shows an example string token that
evaluates to a welcome message for the Lending Library application:
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 193
Chapter 6: Adding business logic
To use a string token in a template or formula:
1. Click String Tokens to find the name of the token you want to add.
2. Click the token name; the syntax for using the token appears in the Template Helper:
3. Copy the token from the Template Helper and paste it into the editor pane where desired. You can format
the token's appearance as shown in the following screen:
194 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Working with templates
4. When you have finished editing the HTML component, save it.
5. Click Save in the page editor.
Rollbase will render the above HTML component on the application page. The screen below shows the resulting
text:
Attaching string tokens
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 195
Chapter 6: Adding business logic
To include string tokens in a published application, you must attach the string tokens to the application. Follow
these steps to attach string tokens to the application:
1. Navigate to the application's setup screen.
2. From the More actions menu, select String Tokens. The Attach String Tokens screens opens.
3. Select the string tokens to attach to the application from the Available column and use the arrow to move
them to the Attached column.
4. Click Save.
Iterating through records
Templates can iterate through a list of records related to the current record. To accomplish this, include a
portion of the template between #LOOP_BEGIN and #LOOP_END tokens and that portion will be repeated for
each record related to the current record.
Note: Having too many loops in templates and formulas may result in performance degradation, because
Rollbase will retrieve many records from the database to compute the results. Use template loops with caution.
In many cases Group Functions or the Query API are better alternatives.
For example, the following Template code renders a list of related items:
<ul>{!#LOOP_BEGIN.R8011504#8108944}
<li>Item: {!R8011504.R8011504} Amount: {!R8011504.amount}</li>
{!#LOOP_END.R8011504}
</ul>
196 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Working with templates
To create a template loop using the Template Editor:
1. In the left dropdown, select the object type related to the current record.
2. Select and copy the #LOOP_BEGIN token.
If you have several views for a related record, you will have a choice of the view to use for iteration that
allows an easy way to filter and sort related records in templates.
3. Create a portion of the template to be repeated for each related record.
4. Select and copy the #LOOP_END token.
Note: The #LOOP_BEGIN token uses original ids of views that will be preserved when your template is published
as a part of an application and installed in another tenant.
Rollbase does not support nested loops (loops within a loop). If you need nested loops consider using an API
instead. For example, to use template tokens from parent record while looping through related record use
object integration name (of parent record) as prefix, try the following:
<ul>
{!#LOOP_BEGIN.R8011504#8108944}
<li>Bill: {!order.name} Amount: {!R8011504.amount}</li>
{!#LOOP_END.R8011504}
</ul>
The following topics provide additional examples.
Loop through specific number of records, comments, and activity trails
Optionally, you can include a maximum number of records to iterate through in parentheses at the end of the
LOOP_BEGIN token. This template will iterate through the first 10 related records, ordered according to the
selected view:
{!#LOOP_BEGIN.R8011504#8108944(10)} … {!#LOOP_END.R8011504}
Using similar syntax you can loop through related comments and activity trail records. The following example
displays two last activity trail records:
<ul>{!#LOOP_BEGIN.$ACT_TRAIL(2)}
<li>{!$ACT_TRAIL.content}</li>
{!#LOOP_END.$ACT_TRAIL}</ul>
Loop through all records
You can loop through records of a different object type within a template, not just through related records. You
must explicitly specify the object name as prefix to template tokens. For example, use {!order.name}, not
the unqualified {!name} You can limit the number of records to display by adding the (numRecords) token at
the end of #LOOP_BEGIN. If not specified, the number of records is limited to 100. Merge field helpers do not
provide support for looping through all records.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 197
Chapter 6: Adding business logic
To accomplish this, follow these steps:
1. Create a list view that sorts and filters records the way you desire. For example, you might sort by the most
recent records updated at value.
2. Click the view name in the object definition and note the value of that view's Original ID.
3. Use the Original ID in the template:
{!#LOOP_BEGIN.all#originalViewId} … {!#LOOP_END.all}
Use the object's integration name as prefix for merge fields used inside loops through all records. Example:
{!#LOOP_BEGIN.all#479484}
{!order.name}
{!#LOOP_END.all}
Instead of {!name}, the {!order.name} token causes Rollbase to replace the merge field with the related
record's name rather than that of the parent object record.
Using EVAL blocks
EVAL blocks allow you to use simple JavaScript-based expressions in a Rollbase template. To debug an EVAL
block in the Template Helper, click EVAL[] Block. Syntax for an EVAL block is as follows:
#EVAL[
JavaScript returning String ]
The following example loops through records but renders <img> tag only for records with amount > 1000:
<ul>
{!#LOOP_BEGIN.R8011504#8108944}
<li>#EVAL[{!R8011504.amount}>1000 ? "<img src='important.gif'>" : ""]
Bill: {!order.name} Amount: {!R8011504.amount}</li>
{!#LOOP_END.R8011504}
<ul>
Creating a record name template
Every record has a special field that displays the record name and provides a link to a record's view page. If
you create an object with the Contact attribute, Rollbase automatically sets the Record Name Template
property with a value of: {!firstName} {!lastName}. Since the first and last name are required, when a
user creates a new record and enters values, the first and last name are used as the value for the Record
Name field. For objects without the Contact attribute, the record name field allows direct user input.
You might want to automatically populate the record name value using a record name template that inserts a
value from another record field. A formula for a record name template can only contain tokens for non-dependent
fields that have stored values for each record. Fields that brings values from other records, such as lookups
for related fields, cannot be used in record name templates. For example, an object with an Auto-Number
field, such as the Invoice Number, works well to in a record name template. If you want to use the value of a
checkbox in a formula, use the #EVAL[] helper, such as:
#EVAL[ {!club_member} ? "Member" : "Non-Member" ] {!title}
To set up a Record Name Template, follow these steps:
1. Open the object definition.
2. Click Edit.
198 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Working with templates
3. Locate the Record Name Template property.
4. From the Template Helper, select one or more merge tokens and paste them in the Record Name Template
field. Add separator characters as desired.
The Record Name Template works like an Expression Field.
• The Record Name field value will not be updated when related records are updated.
• Record Name value is updated when the containing record is updated — not when the record is viewed.
5. To update all existing records using the new template, check the box below the template called Update
names of all existing object records using this template.
6. Click Save.
Email templates
Email templates provide convenient way to generate title, body, and attachments for template-based emails
manually from within Rollbase (for a single record or a group of records). Email templates can be used in/with:
• Email Template fields, see Email Template Field on page 1317.
• Send Email workflow actions, see Workflow actions on page 266
• Workflow triggers, see Trigger overview on page 218
Note: Only users with access to the Templates menu can manage mail and other templates. See The Private
attribute on page 663.
Template marked as Private have important limitations:
• They cannot be used in triggers and workflow actions (since these components are shared by all users).
• They cannot be published as part of an application.
• Once set, a Private flag can only be modified by a user with the Administrative role.
The following example shows an email template that uses merge tokens:
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 199
Chapter 6: Adding business logic
When configuring email triggers, email actions, or sending a group of emails, you can use template syntax to
choose the recipients for the To, CC, and BCC lines. Select an available field of type Email Address from Use
Field drop-down list. That will append the selected token to the Send To text box. You can re-arrange tokens
or move them to another text box. Use space " ", as separator between tokens.
The Email Addresses template only supports tokens for Email Address fields. Other tokens will be ignored.
A single email will be sent and received by all email addresses specified in the Send To, CC or BCC box. If
you wish to send individual email messages - do not specify multiple email addresses.
Creating an email template
To create an email template:
1. Open the object definition for the type of record the emails will be associated with (See Viewing and editing
an Object Definition on page 132).
2. Navigate to the Templates section.
3. Click New Mail Template.
4. Provide a display name for the template.
5. Check the Private box if you want this template to be hidden from other users (checked by default for
non-admin users).
6. Select a template Format: plain text or HTML.
7. Optionally, enter an Integration Code (used by API to find this template).
8. Specify a Subject line for this template. The subject may include any tokens.
9. Specify the body for this template. The body may include any template merge field tokens and loops.
10. Click Save.
200 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Working with templates
Document templates
You can create Rollbase document templates by uploading text or binary files. Document templates can be
used to generate documents such as quotes, purchase orders, reports, and invoices from the values in object
records. Templates can contain content for languages that read right to left (RTL). See Right to left support in
templates on page 207 for details.
Rollbase supports the following document formats for templates:
• Microsoft Word (Only DOCX)
• Microsoft Excel (XLS and XLSX)
• CSV
• HTML
• XML
• PDF forms
• Plain text (TXT)
Document templates can be used in and with:
• Document Template fields; see Document Template Field on page 1317 for more information.
• Template Document workflow actions; see Workflow actions on page 266 for more information.
• Workflow Triggers; see Change Workflow Status on page 233 for more information.
• Template-based Reports; see Working with reports on page 299 for more information.
When modifying an existing text-based template (XML, TXT etc.) you have an option to edit text directly rather
than uploading a new file. In this case, the Template Helper offers the following options:
• Helpers for available template tokens.
• Preview for JavaScript Hosted files.
If you embed any formatting information, visible or invisible, inside the token, the parser will not be able to
recognize the token. For example, {!name} is not recognized as a valid token and it is ignored. If you see that
the parser cannot recognize your token (i.e. it does not get replaced), delete this token and type or paste it in
again.
Microsoft Word templates
You can upload Microsoft Word documents (Only DOCX extension) and use them as Document Templates.
The following graphic shows an example of a Microsoft Word document template, which includes tokens from
a base record (Order) that includes a loop through related items. The body of the loop represents a Microsoft
Word table with a single row:
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 201
Chapter 6: Adding business logic
The graphic below shows the parsed template populated with real data. You can see that original tokens are
replaced with actual values and the styles of the Microsoft Word document are preserved. The date field uses
the date format configured in the current user's tenant. The loop through related records now includes a table
row for each related record (under the Catalog Item column).
Writable PDF forms
PDF templates enable you to use application data to fill fields in writable PDF forms. You first need to create
the template and upload the writable PDF form. You can then map the form fields to object fields of simple
expressions.
Note: In Rollbase Private Cloud, PDF templates are only available if you purchase and install the appropriate
software (see Third party software you can install on page 759).
From the list of templates, click Map Form Fields (available only for PDF document templates) to bring up the
mapping page.
202 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Working with templates
It is not always easy to figure out how particular PDF field must be used as their names might not be informative.
Therefore, we recommend that you first map all fields to easily recognizable tokens and preview the result of
mapping. To preview the resulting document,click the template name to view the template. In the template view
page, click Preview. The following shows the view page for a PDF template.
Note: A writable PDF form remains writable after data is populated. Select the Flatten Populated Form check
box on the Edit Template dialog to make the resulting PDF non-editable.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 203
Chapter 6: Adding business logic
Writable PDF document template example
The following example shows mappings in a document template for an object with location and contact attributes
and address fields in a standard IRS W-9 form. Note that one field is mapped to a single token,
{!streetAddr1}, while another field is mapped to a string template, {!city}, {!state#code} {!zip},
which must be enclosed in quotes.
In the following example, boxes 5 and 6 were populated from a sample record using the mapping shown above:
Creating a new document template
Follow these steps to add a new document template to your application:
1. Create the document that will be used as a template in one of the supported formats described in Document
templates on page 201.
204 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Working with templates
Where appropriate, use tokens as described in Template token syntax on page 188, loops as described in
Iterating through records on page 196, and JavaScript expressions as described in Using EVAL blocks on
page 198.
2. Open the Object definition (See Viewing and editing an Object Definition on page 132) for the object whose
values you want to insert when generating documents.
3. From the navigation banner, click Templates to jump to the Templates section.
4. Click New Document Template.
The Define Document Template page opens.
5. Enter the appropriate values for the following:
• Template name: the display name.
• Integration code: an identifier that can be used in API calls (optional).
• Render as PDF: for HTML templates, when this check box is selected, Rollbase converts the resulting
HTML document to a PDF document. Additional options for generating the PDF are available (See PDF
report options for HTML Template reports on page 305).
• Flatten Populated Form: for PDF forms, when this check box is selected, the resulting PDF is
non-editable.
6. In the Document Name Template field, add a name for the document template. You can use the template
helper to get tokens which could be used to generate file names. If you do not input any value, the name
of the document template is used as the file name by default. Special characters are converted to underscore
in file names.
• You can use the Preview Template link to preview the name of the file that will be generated for the
selected object. If you modify the field values or tokens, the file names will automatically change to take
the new values.
• The generated document template names will be reflected when the document template field token is
used.
Note: It is recommended to use relevant field tokens to name a document template. Avoid using tokens
with special characters or long values (for example, image field tokens and report tokens).
7. In the Upload File field, click Browse to select and upload the prepared template file.
8. Click Save.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 205
Chapter 6: Adding business logic
Communication logs
Communication log records are used to keep track of email messages, phone calls, and other forms of
communication. Unlike audit trail entries, you can add fields to the communication log object definition and
modify its pages and views. Communication log records can be created, edited, or deleted by anyone with
sufficient permissions.
When an object with the Contact attribute enabled (on new or existing objects) Rollbase automatically creates
a relationship with the communication log object and adds list of related communication log records to the
record view page. Otherwise you can create a relationship with a communication log object using the New
Relationship link. For more information on relationships, see Relationships between objects on page 148.
Please note the following:
• The New Communication Log page must include the hidden field Related To. Do not remove this field
from the page.
• The Related To field must be populated with a valid parent record ID when creating a communication log
record programmatically.
• Incoming gmail messages can be converted into communication log (see Incoming Gmail on page 632).
Localization
Rollbase provides full support for localization, including various date formats, currency formats, and multi-lingual
support. See My Localization Settings on page 715 for more information.
New record template
In cases where users will need to create similar records repeatedly on a regular basis, you can use the record
templates feature to streamline this process. New record templates are available from the templates menu for
a particular object definition, or from an object definition's setup page.
206 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Working with templates
To create a new record template, define its name and select an existing record to be cloned.
If you have defined one or more new record templates for your object definition, a drop-down list of these
templates is displayed on the new page for that object definition. Selecting one of them will initiate cloning of
the record using the selected new record template.
You can also use new record templates in create related record workflow actions. For information on workflows,
see Workflow overview on page 256.
Right to left support in templates
Rollbase renders text in document templates and mail templates from left to right (LTR). Unlike on application
pages, Rollbase does not automatically set the text direction based on the language. However, you can edit
your template content to render some or all text from right to left (RTL).
Document templates
For HTML document templates, you can override this behavior and render text RTL for the whole document,
for individual elements, and within an element for a portion of the text. The following attribute and element
enable this control:
• The dir attribute — This attribute specifies the text direction. Its possible values are ltr, rtl, and auto,
where auto renders the text based on the language. Add this attribute to an HTML element, such as a
section or paragraph, to specify the text direction. For example, to render the entire document as RTL, add
it to the html element:
<html dir=”rtl” >
• The bdi element — This element isolates a part of text that might be formatted in a different direction from
other text outside it. It is helpful when the user-generated content has an unknown direction. For example,
if a parent element sets the dir attribute to rtl, and user-generated text could be in Spanish, using the
bdi element ensures that the text is rendered in the appropriate direction.
For Microsoft Word document templates (DOC/DOCX), the default alignment is left. You can use the rich text
editor to keep headings and other titles right aligned.
For XLS, XLSX, RTF, TXT, and XML document templates, you can align the text as required for the language.
Mail templates
To use RTL text in mail templates, do the following:
• Set the email encoding to UTF-8 on the My Settings on page 714.
• When creating a mail template, select HTML as the format. See Email templates on page 199 for information
about creating mail templates. Use the dir attribute and the bdi element as described above to format
the text direction of the HTML content.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 207
Chapter 6: Adding business logic
For more information about language support, see Language support on page 740.
Formulas
Formulas are text templates sent to the JavaScript engine after parsing (i.e. after all merge field tokens have
been replaced with real data). The JavaScript engine executes the formula and returns a single value to the
caller.
Simple Formula Example
This simple formula represents an expression: {!amount}*{!price}*(1-{!discount_proc}/100)
In more complex cases, you can define intermediate variables, flow-control operators, etc. For example, the
following formula calculates monthly payments on a mortgage:
var q = {!mortgage_rate}/12/100; var A = parseInt('{!amount}',10); if (A<=0 || q<=0)
return null; var N= parseInt('{!loan_type#code}',10); if (N<=0) return A*q; return
A*q/(1-Math.pow(1+q, -N));
In such a case, the formula's body will be wrapped into a JavaScript function and the resultant function will
represent the formula's result.
Including Your Own Functions in a Formula
You can include your own functions in a formula:
function formatNum(x) {
if (x instanceof Number && !isNaN(x))
return x.toFixed(2);
return "";
}
function calcStr() {
var y={!amount}*{!discount};
return formatNum(y);
}
calcStr();
Important: If you are using custom-defined functions, your Formula cannot be automatically wrapped and hence
cannot include a return statement outside of a function. In this case place exactly one function call at the end
of your Formula as shown above. The result of this call will be used as the result of the entire Formula. The
Formula's resulting value must be of a certain type that depends on where the Formula is used:
Using custom Java classes in formulas
In Rollbase Private Cloud, you can use custom Java classes in formulas. These classes must be specified
using the shared property CustomClassFilter in the Shared Properties file. See Shared Properties on
page 786 for more information.
Creating and Processing Errors
To interrupt normal flow of JavaScript execution you can throw exceptions. An error message will be displayed
on the screen if UI is involved. For example:
if ({!update_blocked})
throw "Update is blocked";
On the other side if you wish to process errors generated by part of your formula
(for instance, Server-side API) you can use try / catch block. Example:
208 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Formulas
try {
rbv_api.update(...); // Call which may throw Exception
}
catch (e) {
// Process Exception without terminating further execution
}
Writing and debugging formulas
The Formula Helper allows you to select a template token and paste it into a formula's body. The Select ID
control can be used for picklists, lookup, and status fields when you want to select an ID or integration code
for use in your formula. Loops through related records can be used in formulas in the same way as in templates.
The loop's body will be replicated during parsing using data from each related record. Click Validate Formula
for quick validation of the formula's syntax. This will process the formula on an arbitrarily selected object record.
For formula validation and debugging, you must have at least record available.
Note: Formula validation only checks JavaScript syntax validity. For more detailed debugging, use the Debug
Formula button.
Click Debug Formula for detailed debugging. Select the object record to run the formula on in the lookup
window. As illustrated in the following screen shot, the debugger shows the following information:
• Original formula
• Formula parsed using the selected record's data (with line numbers on the left for convenience)
• Debugging output (if any)
• Result of formula calculation
• Error message (if any)
If a particular line in parsed formula is causing an error, that line will be highlighted.
Note: Database transactions cannot be executed in the formula debugger. This means that a formula that
creates, updates, or deletes records will fail in the debugger.
If your formula has no errors, but does not produce the results you expect, you can open the console in your
browser to view any output resulting from running the script, including error messages. To open the console
in Chrome, use the keyboard shortcut command Ctrl + Shift + i or click F12. To open the console in Firefox,
use the keyboard shortcut Ctrl + Shift + k or select Web Console from the Web Developer submenu.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 209
Chapter 6: Adding business logic
Note: For simple operations like SUM and COUNT, looping through related records should be replaced by
much more efficient group functions as described in Group functions on page 215.
Formula return types
The return type of a formula must be appropriate for its context. The following table outlines the return types
of the formulas:
Type of Formula Return Type
Formula fields created as part of an object definition selected Decimal Currency Integer String Boolean
by user per field. Can be one of the following: Date Date/Time
Conditions used in triggers and workflow actions Boolean
Expressions used in triggers to change a field's value Same as target field's type
Conditions used in field-level validations String (error message) or null (no error)
Values calculated in gauge components Numeric
#EVAL[ ] helpers that may be embedded in any Template Any, will be converted into a string
210 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Formulas
Improved Formula Debugging
This topic includes the following:
• Improved formula debugging on page 211
• New debugging variable for trigger formulas on page 212
Improved formula debugging
The formula debugger has the following improvements:
• When you click the Debug Formula button, the record selector popup window resizes dynamically to 80%
of the width of the hosting window and 95% of its height.
• When you select a record, the formula debugging window is also sized dynamically.
• The formula debugging window now contains a toolbar to navigate through window sections. The toolbar
does not scroll off of the screen.
The following screen shows the new formula debugging window.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 211
Chapter 6: Adding business logic
New debugging variable for trigger formulas
The trigger formula debugger cannot execute database transactions. In previous Rollbase releases, a formula
that created, updated, or deleted records failed in the debugger.
This release introduces a new variable, rbv_debugFormula, that allows you to conditionalize code that
requires a database transaction and debug the rest of the formula. Rollbase uses this variable when running
the formula in the debugger, but does not use it when running the actual trigger in the application.
212 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Formulas
Use the following code pattern to detect both cases. In this example, the function returns without creating a
record if the variable rbv_debugFormula is present and has a value.
function createRBRecord(rbObjectName,recordData,isAttachReq,attachData){
if(this.rbv_debugFormula !== undefined && this.rbv_debugFormula){
rbv_api.println("Skipping create record for "+ rbObjectName);
return;
}
varrecId=rbv_api.createRecord(rbObjectName,recordData);
if(isAttachReq===true && recId){
rbv_api.attach(attachData["relName"],attachData["objName1"],
'{!id}',attachData["objName2"],recId);
}
}
Examples of valid string tokens
String tokens such as {!lastName} will be replaced by values from text fields before sending the formula to
the JavaScript engine. Unlike numeric tokens that can be used in the formulas as is, text tokens typically must
be enclosed in quotes to produce meaningful results. Using an example for a record where Ellison is the last
name and John is the first, the following table shows valid ways of using the name in a formula.
Token Usage JavaScript Results
{!amount}*{!counter} 20.5*2 Valid JavaScript expression
{!lastName} Ellison No variable "Ellison" exists, this
usage will cause an error
"{!lastName}" "Ellison" Valid JavaScript expression
"{!lastName}, "Ellison, John" Valid and efficient concatenation of
{!firstName}" two tokens
"{!lastName}"+ ", "Ellison, John" Valid, but an inefficient way to
"+"{!firstName}" concatenate tokens - see efficient
example above
You can also use custom string tokens in formulas. See Creating and using string tokens on page 193 for more
information.
Using dates in formulas
For the date return type, formulas can use the JavaScript Date class. Formulas also can optionally return the
number of milliseconds between midnight of January 1, 1970 and the specified date. Typically, you will create
an instance of JavaScript Date class and call getTime() on it. The following formula returns the current date
shifted forward by 24 hours (calculated using the current user's time zone):
var d = new Date(rbv_api.getCurrentDate());
return d.getTime() + 24*60*60*1000;
Note: Avoid using the default constructor new Date() since it will return date in server's time zone which
may be very confusing. Date("{!date_field}") will create a Date object corresponding to your date field.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 213
Chapter 6: Adding business logic
Example of date usage in formulas
You can use the standard JavaScript Date object in formulas. The following formula shows how to calculate
the difference in days between a Rollbase Date field value and the current date, taking into account the user's
time zone setting:
var dt = new
Date("{!date_field}");
var today = new Date(rbv_api.getCurrentDate());
var day = 24*60*60*1000;
// Length of 24 hours on milliseconds
var days1 = Math.floor(dt.getTime()/day);
// Rounded down
var days2 = Math.floor(today.getTime()/day);
return days1 - days2;
Note: String representations of date fields in formulas (e.g. the merge field {!date_field} above) automatically
uses the correct time zone from the current user. To ensure that current date uses the correct time zone as
well, use the getCurrentDate() API.
Example using images to represent record status
To create an HTML icon with an image that reflects the current status of a particular record, follow these steps:
1. Create several Shared Icon fields to hold your icons.
2. Create a formula field with return type string and the following formula:
if ("{!status#code}"=="CRE") return "{!order.created_icon#html}";
else if
("{!status#code}"=="SHI") return "{!order.shipped_icon#html}";
else if
("{!status#code}"=="CAN")
return "{!order.cancelled_icon#html}"; return "";
3. Add this formula field to views and view pages as needed. It will generate HTML with an image field which
depends on the record's status.
Note: Please note that the formula above uses status integration codes rather than IDs. This approach ensures
that the formula above can be published as part of application and installed without requiring changes. Never
rely on IDs in formulas if you plan on publishing your application.
Formula execution limits
You can use any valid JavaScript code in your formulas, including arrays, for loops, etc. However, to protect
our computational resources, the total execution time of any formula is limited to 3000 ms. If server-side script
takes too long to execute, it will be aborted by the system. The length of a parsed server-side script cannot
exceed 10KB. This is normally not an issue and can only become an issue if you're using loops through a long
list of records. Try to avoid using long loops.
Note: Rollbase Private Cloud customers may change the limits specified above. For information about
configuring Private Cloud, see Shared Properties on page 786.
214 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Formulas
For obvious reasons, server-side formulas cannot make use of the Document Object Model (DOM) or third-party
JavaScript libraries. However, core JavaScript objects (Math, String and Date) are available for server-side
scripting. If a formula or template is used within another formula or template, it will be evaluated before being
used. However, this useful feature can result in endless recursion (consider Formula field my_formula with
body {!my_formula}+1). To prevent endless recursion, the system limits maximum recursion level (number of
times formula is called from within another formula) to 10.
Group functions
Group functions are used to calculate the value of an expression from groups of related records.
Note: Group functions are retained for backward compatibility. If you know SQL, use Query APIs instead of
group functions because all the operations that you can perform using group functions can also be performed
using Query APIs.
Rollbase formulas support four types of group functions:
Function Result Parameters
#CALC_SUM.R8011457( expression SUM of expressions for Expression is mandatory and must
| condition ) records where condition is be numeric. Condition is optional
true. (default to true).
#CALC_COUNT.R8011457( Counts all records for which Expression is optional (default to 1)
expression | condition ) expression is not null and and must be numeric. Condition is
condition is true. optional (default to true).
#CALC_MAX.R8011457( expression MAX of expressions for Expression is mandatory and must
| condition ) records where condition is be numeric. Condition is optional
true. (default to true).
#CALC_MIN.R8011457( expression MIN of expressions for Expression is mandatory and must
| condition ) records where condition is be numeric. Condition is optional
true. (default to true).
You can also run group functions on the entire set of object records. Use the object integration name instead
of a specific relationship name, such as:
#CALC_SUM.invoice( amount | true )
When writing expressions and conditions for group functions do not use tokens from the Select Merge Token
box; rather, use the Group Token box for fields from related records.
Note: Inside a group function body, you must not use tokens in {! .. } format or equate hard-coded numeric
or string values with the special tokens. For example, the TODAY token specifies the current time, but you
cannot get yesterday’s time using (TODAY-1). This results in an error.
Whenever faced with a restriction using group functions, consider using the Query APIs as an alternative (see
Query API on page 950).
Group functions use SQL syntax rather than JavaScript syntax for expressions and conditions. In simple cases
you may not notice a difference. For Group Function conditions you can use the following special tokens:
• TODAY for the current time
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 215
Chapter 6: Adding business logic
• WEEK for 12PM of last Sunday
• MONTH for 12PM of 1st day of the current month
• QUARTER for 12PM of 1st day of the current quarter
• YEAR for 12PM of 1st day of the current year
• CURR_USER for id of the currently logged in user
You can also use integration codes from picklists and status fields. Examples of group functions:
• Maximum value of amount field among related records created in the current quarter:
#CALC_MAX.R8011457( amount | createdAt>=QUARTER )
• Count the number of related records where address1 field is not null:
#CALC_COUNT.R8011457( address1 )
• Sum the amount field for all invoice records with a due_date after January 1st current year:
#CALC_SUM.invoice( amount | due_date>=YEAR );
Typical mistakes in formulas
The following sections summarize some typical mistakes and inefficiencies in formulas.
Include tokens in quotes
Do not forget that template tokens like {!name} are not JavaScript variables. They are replaced by actual values
before being sent to the JavaScript engine. While numeric values can be used as is, strings are typically
enclosed in quotes to form a meaningful result.
Original Formula Parsed Results Comments
counter += {!amount}; counter Correct You can treat numerical tokens as
+= 100; variables.
if ({!country#code} == "US") If JavaScript error CA variable does not exist.
(CA == "US")
if ("{!country#code}" == "US") Correct You must always enclose string tokens in
If ("CA" == "US") quotes or make them a part of larger string.
216 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Triggers and workflows
Unnecessary quotes
You can often use the fact that template tokens will be replaced with real, non-quoted values to your advantage
by simplifying token concatenation. You don't have to use JavaScript to concatenate tokens - the template
parser can do it for you.
Formula Comments
var ln = "{!lastName}"; Correct but inefficient
var fn = "{!firstName}";
return ln+", "+fn; var ln = "Ellison";
var fn = "John";
return ln+", "+fn;
return "{!lastName}, {!firstName}"; return "Ellison, Correct and efficient
John";
Avoid loops in formulas
Although you can use template loops in formulas, be aware that they can result in very long JavaScript after
parsing; that script could be aborted by Rollbase due to formula length and execution time limitations. Consider
this example:
{!#LOOP_BEGIN.R12345}
// Do some processing
rbv_api.setFieldValue(...);
{!#LOOP_END.R12345}
The code inside the loop will be replicated for each record in the loop. A much more efficient approach would
be to use a JavaScript for() loop:
var ids = rbv_api.getRelatedIds("R123456", {!id});
for (var i=0; i<ids.length; i++) {
var ordered = ids[i];
rbv_api.runTrigger("order", orderId, "trUpdate");
}
In this example, the formula obtains a list of related IDs, loops through them all and invokes a trigger on the
corresponding related record. You may also use Query API to extract data instead of loops through data records.
Warning: If a number record in a loop is large you may hit timeout limit for formula execution.
Using Comments
You can use valid JavaScript comments in your formulas. However please keep in mind that:
• Comments enlarge total length of formula and may potentially lead to hitting limit on overall formula length.
• Avoid using //-style comments since they may lead to error should carriage-return in your formula accidentally
be lost. Use the /* */ style for comments in JavaScript formulas.
Triggers and workflows
Rollbase triggers provide a way to add user-driven and programmatic business logic based on record changes
or at scheduled times. Workflows support a structured user-driven flow of records through the user interface.
To use workflows, you must first enable the Workflow attribute. While triggers are often used together with
workflows, they do not have to be used with workflows and the Workflow attribute does not have to be enabled
on an object to use triggers.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 217
Chapter 6: Adding business logic
Watch Web App Trigger Examples to see how triggers can update fields in related records and create new
records.
Note: In addition to the built-in trigger types explained in this documentation, Rollbase Private Cloud users
can develop custom triggers using Java code (Developing a Custom Trigger on page 225).
Trigger overview
Triggers can perform automated validation, notification, and data manipulation. You can configure triggers to
fire upon events such as record creation, update, and deletion, as a result of a workflow flow action, and you
can run triggers manually.
The triggers available for an object depend on that object's properties and components. For example, some
triggers are only available when object attributes such as Workflow or Audit Trail are enabled. Others depend
on components that you must create first, such as a conversion map or template. The timing options available
also depend on the type of trigger you are creating.
A trigger is associated with an object definition. You can view or create new triggers from the Triggers component
table. Depending on the type of trigger, its formula can calculate and set values or specify a condition that
causes the trigger to fire.
To conditionalize a trigger, specify a formula that returns a boolean value. If the value evaluates to false or null
for a particular record, the trigger will not run on that record.
For example, to run triggers only for large orders, you could use a formula such as:
{!amount} > 10000
A single line of JavaScript such as that shown above that evaluates to true, false, or null does not require a
return statement. However, multi-line conditions such as those shown in other examples do require a return
statement.
When defining a trigger you can also specify:
• Whether or not the trigger is deployed. Undeployed triggers will not run.
• An integration name, which is good practice and allows you to invoke the trigger using the rbv_api.runTrigger()
on page 985 method.
• Whether to run a trigger only when a particular field has changed its value (this will only affect After Update
triggers). You can use template and formula fields in this condition, allowing you to determine whether or
not the trigger should fire based on changes to a group of fields instead of a single field.
• If a trigger updates an existing record or creates a new record, you can specify whether dependent triggers
(before/after update, before/after create) should also run. Use this option with caution, since it may lead to
inefficient nested trigger invocations.
Built-in triggers provide the following capabilities, which are described further in the linked content:
• Send Email on page 249
• Create Audit Trail Record on page 233
• Validate Record Data on page 251
• Unique Fields Combination on page 249
• Update Field Value on page 249
• Change Workflow Status on page 233
218 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Triggers and workflows
• Create New Record on page 234
• Attach Related Record on page 233
• Create Template Document on page 234
• Run Triggers on Related Records on page 237
• Object Script on page 237
• HTTP triggers on page 234 Send GET, POST, or SMS messages
The graphic below illustrates the general order in which Rollbase runs triggers when you specify a timing option.
See Trigger timing options on page 220 for more details.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 219
Chapter 6: Adding business logic
The following topics provide guidance on using triggers and the general steps for creating them:
• Trigger rules and restrictions on page 220
• Trigger timing options on page 220
• Best practices for trigger formulas on page 221
• Delayed and repeating triggers on page 222
• Creating a trigger on page 223
• Example: Set field based on a workflow status change on page 251
• Debugging complex triggers on page 253
• Debugging delayed triggers on page 255
Trigger rules and restrictions
Triggers can work in combination. One trigger might invoke or rely on the results of other triggers. The following
rules ensure that dependencies between triggers do not result in endless recursion:
1. The total number of triggers invoked in a single update, create, or delete operation is limited to 100 for
immediate triggers and 20 for delayed triggers (these numbers may vary for Private Cloud customers).
2. Per triggering event, the same group of triggers, for example, those timed to occur after an update, will not
run twice on the same record.
3. Per triggering event, each trigger only runs once on each record.
4. Total execution time for a group of triggers, such as those timed to occur on create, cannot exceed 30
seconds (this limit may vary for Private Cloud customers). Time of HTTP calls (POST and GET) is excluded
from this limit.
Use the trigger debugger to verify that grouped triggers work as you expect. See Debugging complex triggers
on page 253 for more details.
Trigger timing options
When you create or configure a trigger, you can optionally select when you want it to run during the lifecycle
of a record. The interface only displays valid options for the type of trigger you are creating. Timing options
that fire before a record is committed, such as a trigger to validate data, are different from those available for
triggers that run after commit. In some cases, options show but are disabled. For example, in a new record
trigger, all timing options are shown but Before Create and After Delete are disabled because they are not
applicable when creating a new record.
Multiple triggers can have the same timing option. In this case, the order in which they run is determined by
the order in which they appear in the object definition's Triggers table. The following table briefly describes
each Timing Option:
Timing Option When Run
Before Create Before a record is created
After Create After a record is created (most commonly used timing)
Before Update Before a record is updated
220 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Triggers and workflows
Timing Option When Run
After Update After a record is updated
Before Delete Before a record is deleted
After Delete After a record is deleted
Before Restore Before a record is restored from the Recycle Bin
After Restore After a record is restored from the Recycle Bin
On Finalize After input from grid controls, embedded quick create, and survey components (if present on
processed. This option only applies when an individual record is created or updated through the
and not through an API.
On Login When a user or portal user logs in
On Logout When a user or portal user logs out
When a record is created, Rollbase:
1. Creates a new record without committing it into the database.
2. Runs all triggers with Before Create timing.
3. Commits the new record to the database.
4. Runs all triggers with After Create timing.
When a record is updated, Rollbase:
1. Runs all triggers with Before Update timing (note that the record is not updated at this point of time).
2. Commits the actual record update in the database.
3. Runs all triggers with After Update timing. When a record is attached or detached using links in a related
list component, the system runs After Update triggers on both sides of the relationship.
When a record is deleted, Rollbase:
1. Runs all triggers with Before Delete timing.
2. Moves the record to Recycle Bin.
3. Runs all triggers with After Delete timing.
When a record is restored from the Recycle Bin, Rollbase:
1. Runs all triggers with Before Restore timing.
2. Moves the record from the Recycle Bin.
3. Runs all triggers with After Restore timing.
Best practices for trigger formulas
Triggers use formulas to calculate conditions, change field values, or perform other logic. To write efficient
formulas, follow these guidelines:
1. Use the return keyword only in complex formulas with intermediate variables:
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 221
Chapter 6: Adding business logic
• Efficient:
({!amount} > 1000)
• Inefficient:
if ({!amount} > 1000)
return true;
else
return false;
2. Avoid looping through related records. Use group functions instead (looping through related records can
seriously affect performance).
3. Always use integration codes instead of IDs for status and picklist items (this applies to template fields and
formula fields as well). Logic based on IDs will not work correctly in applications published to other tenants
because the IDs change.
Delayed and repeating triggers
If you would like a trigger to be delayed relative to a particular date and time, you can specify delay criteria.
A trigger can be delayed relative to the current time or relative to the value of any date or date/time field for
the selected record. The example below shows a trigger that will run seven days after the last record's update.
You can also specify criteria to run a particular trigger periodically, including the maximum number of times to
run. The example below shows a trigger that runs every week starting from the last record's update, up to 3
times.
You can view stored delayed triggers by clicking Queue on an object view page. A queue displays up to 1000
stored triggers and shows when they will run. It can be filtered by the selected object record.
When setting triggers to run after a delay or repeat, keep the following in mind:
• Be careful when using delayed or repeated triggers to avoid unnecessary recursion.
• For delayed triggers, the timing options before or after update or creation are irrelevant.
• Object Script running in delayed or recursive triggers requires the appropriate permissions be set for the
Server API role. For information about permissions, see Access control on page 647.
• Delayed and recursive triggers do not run if a customer tenant is expired or inactive.
• Recursive triggers are not supported for the Before Delete and After Delete timing options, because the
record is already deleted before the second attempt at firing the trigger.
222 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Triggers and workflows
• The Debug Formula button in the trigger formula editor for delayed or recursive triggers uses the Server
API role to calculate permissions.
• If a Date field is used as relative point for a delayed trigger, its value is interpreted as 12:00 am. in the user's
time zone. If a Date or Date/Time field has no value, no delay will be set and the trigger will run immediately.
See Debugging delayed triggers on page 255 for more on debugging delayed triggers.
Creating a trigger
This topic covers general steps to create a trigger. For specific examples, see Example: Set field based on a
workflow status change on page 251, or watch Web App Trigger Examples to see how triggers can update fields
in related records and create new records.
1. Navigate to the object definition. For example:
From an application page, select Object Definition from the Page Options menu:
2. In the ribbon of object components, click Triggers:
3. Click New Trigger.
The New Trigger screen opens.
4. Select the trigger type and click Next.
The options available on the next screen depend on the type of trigger you select.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 223
Chapter 6: Adding business logic
5. Finalize the definition of your trigger using the controls on this screen:
• Deployment Status — If checked, the trigger will run. If unchecked, the trigger will not run.
• Trigger Timing — Causes the trigger to fire during events in a record lifecycle. See Trigger timing options
on page 220 for details.
• General Properties — Enter a name and an integration name. If you selected Before Update or After
Update timing, choose the field(s) for which an update should fire the trigger.
• Trigger Properties — Read the Tip to understand what type of formula the trigger expects. Use the
Template Helper and formula editor to create and validate the expression. See Best practices for trigger
formulas on page 221 for more information.
• Trigger Delay Time — Optionally, set a delay time. See Delayed and repeating triggers on page 222 for
details.
• Recursion — Optionally, set times for the trigger to repeat. See Delayed and repeating triggers on page
222 for details.
6. Click Save.
Rollbase creates the trigger and it appears in the Triggers table in the object definition. You can control
the order in which triggers fire by reordering them in this table.
Working with custom triggers
Rollbase Private Cloud users can extend the native Rollbase capabilities by creating custom Java-based
triggers, JSP pages and custom authentication methods. This topic explains how to develop and deploy these
custom components in any Rollbase Private Cloud instance.
Note: Rollbase uses Java 8.
To develop a custom trigger, you must understand how Rollbase represents a trigger programmatically. A
Rollbase trigger requires the following programmatic and configuration definitions:
• A design-time class (configurator) that extends the class
com.rb.core.services.event.TriggerConfig.
• A runtime class that extends the class com.rb.core.services.event.RuntimeTrigger.
• An event node in the config/events.xml file that describes the trigger.
• Language translations of the trigger’s name and description in the res/lang_xx.properties resource
file.
Custom development toolkit for custom triggers
Rollbase provides a custom development toolkit with a sample custom trigger for your reference. You can
download the custom development toolkit (customt.zip) from the Rollbase Private Cloud installer location
(typically, https://s3.amazonaws.com/rlb-prod-public/live-prod/artifacts/customt.zip).
224 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Triggers and workflows
In the custom development toolkit, refer to the following files to implement or understand custom trigger
development using the sample custom trigger custom.jar:
• The runtime time class, CustomTrigger.java, located at customt.zip\customt\src\trigger\:
This class contains abstracts methods that define the trigger action.
• The design-time class, CustomTriggerConfig.java, located at
customt.zip\customt\src\trigger\: This class contains abstracts methods that define trigger
properties.
• The custom trigger project JAR file, custom.jar, located at customt.zip\customt\: This is the custom
trigger project file that contains all the trigger-specific class files.
To create a custom trigger from scratch, refer to Developing a Custom Trigger on page 225.
Developing a Custom Trigger
The section describes how to develop a custom trigger. Progress recommends that before developing a custom
trigger, you understand the implementation and configuration required for a trigger (Working with custom triggers
on page 224) and review the reference implementation in the custom development toolkit (Custom development
toolkit for custom triggers on page 224).
Perform the steps below to develop a custom trigger:
1. Create a Java project for custom trigger development.
This project should contain implementation classes—primarily, a design-time trigger class and a runtime
trigger class.
2. Create a design-time class that defines trigger properties. This class must implement the following abstracts
methods:
• getRuntimeClassName(): Returns the fully-qualified name of the run-time trigger class
• getTimingMask(): Returns the trigger's timing options (defined in ITriggerConstants interface)
joined by the binary OR
• getConfigHTML(): Returns an HTML string with controls to configure trigger -specific information
during the trigger configuration process.
• getVerifyJS(): Returns JavaScript string that validates input data during the trigger configuration
process.
• getProperties(): Returns the trigger's properties after the trigger configuration is completed
• isSystem(): Returns true for system batch job triggers and false for other triggers.
Note: Custom Development Toolkit provides a sample design-time class, CustomTriggerConfig.java,
for your reference.
3. Create a runtime class that defines the trigger action. This class must implement the following abstract
methods:
• trigger(): Performs the trigger-specific action and contains the trigger's logic.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 225
Chapter 6: Adding business logic
To perform the trigger-specific action, a runtime class uses the TriggerRunner instance, which is passed
as a parameter to get the necessary run-time information, including:
• getCustomer(): Returns the current trigger instance representing customer zone
• getHttpRequest(): Returns an HTTP request for UI-driven triggers
• getSharedValue(): Returns the value set by previous triggers (in a chain)
• getTransaction(): Returns the current database transaction. This instance is passed to the
data-handler classes to perform update operations
• getUser(): Returns the currently logged-in user (if any)
For more information about the run-time information, refer to the JavaDoc folder in the Custom Development
Toolkit.
Warning: To prevent your data from getting corrupted, ensure that there are no create, commit, or
rollback transactions in your custom trigger. Instead, use transaction instance from the
TriggerRunner instance.
Note: Custom Development Toolkit provides a sample run-time class, CustomTrigger.java, for your
reference.
4. From the System Console > Control Panel > Configuration > Events, modify the configuration and add
the custom trigger’s event under the <events> tag in the following format to make the custom trigger
available in Rollbase:
<Event id="name_of_Run-time_Class"
className="fully_qualified_name_of_design-time_class"/>
For example, if your runtime trigger class name is CustomTrigger and design-time trigger class name is
CustomTriggerConfig, then add the following event under the events tag:
<Event id="CustomTrigger" className="trigger.CustomTriggerConfig"/>
5. In the lang_en.properties file and, optionally, resource files of other languages, add the custom trigger’s
language translations in the following format:
name_of_Run-time_Class_name={Trigger_name_to_be_displayed_on_Rollbase_pages}
name_of_Run-time_Class_type={Trigger_type_to_be_displayed_on_Rollbase_pages}
name_of_Run-time_Class_descr={Trigger_description_to_be_displayed_on_Rollbase_pages}
For example, if your run-time trigger class name is CustomTrigger, then add the following entries in
lang_en.properties:
CustomTrigger_name=Custom Trigger
CustomTrigger_type=Custom
CustomTrigger_descr=Sample Rollbase triggers
If you installed PAS, the default location of this file is Pas_Instance\rollbase\res.
6. Compile the custom trigger code (with atleast two Java classes) to create a JAR file.
Ensure that the following Rollbase JAR files are in the CLASSPATH during compilation.
• rb_util.jar: Rollbase utilities file.
226 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Triggers and workflows
If you installed Progress Application Server (PAS), the default location of this file is
Progress\Rollbase\Pas_Instance\common\lib.
• rb_core.jar: Core Rollbase classes file.
If you installed PAS, the default location of this file is Pas_Instance\webapps\prod1\WEB-INF\lib
7. Build a JAR file of your java project.
Note: The Custom Development Toolkit includes ANT build.xml file that you can use to build a custom
JAR file.
8. Stop your Web server(s).
9. Copy the JAR file to the WEB-INF/lib directory of all the servers that must execute this custom trigger:
• master: Master server that serves the master zone only
• prod1: Production server that serves all customer zones
• workflow: Serves delayed events for all zones
• search: Serves search calls for all zones
• webapi: Serves SOAP calls for all zones
• rest: Serves REST calls for all zones
• storage: Serves spreadsheet imports for all zones
10. Restart your Web server for the changes to take effect.
Enusre that the modified events.xml and lang_xx.properties files are located in the shared directory
of your Rollbase Private Cloud installation.
Your custom trigger will then be available in Rollbase and appear as one of the trigger types on the New
Trigger page (Creating a trigger on page 223).
Using Custom JSP Pages
Custom JSP pages can be used in Rollbase the same way as other external pages by creating a Tab of type
“Web” and assigning the URL of that page to it.
If you wish to use Rollbase classes in your custom JSP:
1. Ensure that rb_core.jar is available to Tomcat when serving your JSP.
2. Use CustomUIUtil.getUser(request) to ensure that the visitor has a valid Rollbase session.
3. Add the Rollbase session ID to the JSP’s URL (cookies are not always reliable), for example:
custom.jsp?sessionId={!#SESSION_ID}
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 227
Chapter 6: Adding business logic
Here is a simple example of a custom JSP page:
<%@ page import="com.rb.core.data.user.User" %>
<%@ page import="com.rb.core.ui.web.CustomUIUtil" %>
<%
User u = CustomUIUtil.getUser(request);
%>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv='content-type' content='text/html; charset=UTF-8'>
<title>Custom Page</title>
</head>
<body>
<h1>Welcome, <%=u%></h1>
</body
</html>
Configuring a Custom Trigger to Use a Custom Object
Prerequisite:
Perform the below steps before installing an application
1. Download custom.zip file and extract.
2. Copy customt.jar to following war file or tomcat installation path. Better to copy to war files to avoid problem
when you are working in cluster environments.
• master/WEB-INF/lib (tomcat/webapps/master/WEB-INF/lib)
• prod1/WEB-INF/lib (tomcat/webapps/master/WEB-INF/lib). Copy to all prod machines.
• rest/WEB-INF/lib (tomcat/webapps/rest/WEB-INF/lib)
• webapi/WEB-INF/lib (tomcat/webapps/webapi/WEB-INF/lib)
• search/WEB-INF/lib (tomcat/webapps/search/WEB-INF/lib)
• storage/WEB-INF/lib (tomcat/webapps/strorage/WEB-INF/lib)
3. Update event.xml to include Custom trigger configure details, from Rollbase 5.0 you can configure this from
System console. Follow this link to add new entry to events.xml . With out this change you can’t install this
application, since this application object configured with custom trigger.
4. If you want to use Custom Object in formual (sample application include this feature) , update following
shared property, CustomClassFilter = com.custom.CustomObject . More details about Custom Object are
available in below section. From Rollbase 5.0 shared properties can be updated from system Console. If
you don’t configure this property, Custom Object Field column displays error message.
5. Restart your Tomcat
Getting Started
This application demonstrates how you can configure Custom Trigger and how you can use Custom Object in
Rollbase. This Application has two object Object A, Object B and they are related to each other with relationship
of M:M.
Object A – configured with Custom Trigger and used Custom Object in Custom Object Field formula field. In
below sections, we will see in details about Custom Trigger and Custom Objects.
Object B – Have integer field configured which will be updated by Custom Trigger.
228 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Triggers and workflows
Custom Trigger
Custom Trigger can be developed and deployed only in the private cloud. Refer Developing a Custom Trigger
on page 225 in Rollbase. Sample custom trigger attached to development kit only run an Application that have
at least two objects and both are related, also when you configure trigger for an object other side related object
should have integer field.
Sample custom trigger code run on related object records, increment integer value of related object by 100 on
each run, when value exceeds 1000, it throws error.
After configuring the custom trigger, the new custom trigger itemwill be available in the Trigger page. When
you select the custom trigger, the Tirgger configuration page view will appear. Configure Relationship Name
and Related Object integer field name from UI as shown in the sample screenshot below.
These two values are persisted and will be used by custom trigger code when it is run.
Following code is used to render these two fields in UI (CustomTriggerConfig.java)
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 229
Chapter 6: Adding business logic
Following code is used to persist the value to Trigger properties (CustomTriggerConfig.java)
Following code uses the above two values when trigger runs (CustomTrigger.java)
230 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Triggers and workflows
Custom Object
Custom Object can be used in Rollbase formulas. In order to use custom object user should make Custom
Object available in tomcat class path. Sample attachment has CustomObject.java and this class is made part
of customt.jar and copied as mentioned. You can build separate jar and copy jar to all war files as mentioned
in the prerequisite section.
After you copy jar you should update following shared property
CustomClassFilter=Regular expression which matches classes you want to allow
Below section provided sample how to use Custom Object in Rollbase.
Sample
CustomClassFilter = com.custom.CustomObject
Formula field, returns number of related items
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 231
Chapter 6: Adding business logic
CustomObject.java
Sample class written to wrap simple ArrayList functionality, you are free to write this class as complex as you
need.
Using Custom Objects in Formulas
You can use custom Java objects (available on CLASSPATH) in Rollbase formulas. To do that please add
permissions for Rollbase formulas to use your objects by adding entry to the Shared Properties:
CustomClassFilter=RegEx expression which matches classes you want to allow
Example: consider formula below
var x = new Packages.java.util.ArrayList();
x.add("TEST");
return x.size();
This formula will cause an error in standard Rollbase installation since formulas are not allowed to use Java
object ArrayList. However this will change if you add the following entry to stared.properties configuration file:
CustomClassFilter=java.util.ArrayList
After this change formula above is valid and produces correct result.
232 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Triggers and workflows
Note: The CustomClassFilter entry is a regular expression and can include any regex syntax.
Trigger types
The following sections describe the types of triggers you can create.
Attach Related Record
This trigger attaches the current record to a related record (i.e. establishes a relationship between two records).
To use this trigger, select or define:
• A relationship between current object and a target object.
• A formula that calculates the ID or array of IDs of the related record (instead of a condition formula). If this
formula returns a null or negative number, this trigger is ignored.
The following formula example uses the query API to determine the ID of the record to be attached:
var arr = rbv_api.selectQuery("SELECT id FROM contact WHERE status=?", 'Ready');
var ids = new Array();
for (var k=0; k<arr.length; k++) {
ids[k] = arr[k][0];
}
return ids;
Note: You must create at least one relationship for the current object in order to use this type of trigger.
Change Workflow Status
This trigger changes the workflow status of a record. To use this trigger, select a target workflow status. Use
a trigger condition formula to make this change optional. Refer to the Update Field Value on page 249 for details
about the access control policy and dependent triggers.
Note: You must create at least one workflow status before you can use this type of trigger.
Corticon Decision Service
A Corticon Decision Service trigger allows you to incorporate sophisticated automated decision-making
capabilities in your app. See Automating business decisions with Corticon rules on page 277 for information on
configuring this type of trigger.
Create Audit Trail Record
This trigger creates a new audit trail record based on a template defined by you and attaches it to the current
or related record. To use this trigger, select an object (either the current record's object type or that of a related
record) and specify the template to populate the audit trail record's text.
The Audit Trail property must be enabled for a given object definition to create this type of trigger.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 233
Chapter 6: Adding business logic
Create New Record
This trigger creates a new record from the current record using a conversion map. See Converting records on
page 160 for information about conversion maps. To use this trigger, select a conversion map (which determines
the type of the resulting record). Also, refer to Update Field Value on page 249 for details about access control
policies and dependent triggers.
Note: You must create at least one conversion map to convert the current record into another record to use
this type of trigger.
The ID of the newly created record is available for other triggers in the update chain through the shared value
named newID_objectName. The following Object Script example reads the ID of the newly created record
and creates an activity log record:
var newID = rbv_api.getSharedValue("newID_entity");
rbv_api.createActivityLog("entity", {!id}, "New record created: "+newID);
Create Template Document
This trigger creates a template-based document for the current record and (optionally) sends it in an email as
an attachment. For instance, you can use this trigger to generate an invoice and send it to a customer. To use
this trigger, configure the following:
• A document template or template picklist field (which selects a document template based on the value of
that field for a given record) to use. See Document templates on page 201 for information about document
templates. See Document Template Field on page 1317 for information about template picklist fields.
• The File Field, which is a File Upload field that determines where to store the resulting template-based
document. See File Upload field on page 1312 for more information.
• An Email Template and a Send To email address to which to send the resulting document (optional). See
Email templates on page 199 for information about email templates.
You can create a Document Template Field on page 1317 that generates a new document each time you view
it. This trigger is similar, but it generates and stores the template document in a particular field and its contents
do not change even if other field values change.
Note: You must create at least one document template and at least one File Upload field before you can use
triggers of this type.
HTTP triggers
You can use triggers to send HTTP Get and Post requests and send SMS messages.
Processing Responses from HTTP Triggers
After the HTTP response is retrieved by GET, POST, or SMS Trigger, the system stores two values and makes
them available for subsequent Triggers through the getSharedValue() API (see rbv_api.getSharedValue() on
page 1014):
Name Value Example
ReturnStatus HTTP Status rbv_api.getSharedValue("ReturnStatus")
ReturnBody HTTP Body rbv_api.getSharedValue("ReturnBody")
234 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Triggers and workflows
For example:
1. Create an HTTP GET or HTTP POST trigger.
2. Create an Object Script on page 237 and configure it to run immediately after HTTP trigger. Use the following
API calls in Object Script trigger:
var code = rbv_api.getSharedValue("ReturnStatus");
var body = rbv_api.getSharedValue("ReturnBody");
Now you can analyze HTTP return code and response's body and perform appropriate action.
Tip: You can create powerful integrations by sending HTTP requests and then processing the results in a
subsequent Object Script Trigger. Please note that second etc. HTTP call will override shared values set on
the first call. Store these values in intermediate variables if you need to preserve them.
Send HTTP post request
This Trigger sends an HTTP POST request to a specified URL. It can be used to send any XML (i.e. SOAP)
or other POST request to a third party containing information and instructions gathered from Rollbase record
data. To use this Trigger, select:
• Enable retry checkbox if you want to enable retry options for the trigger. By default, this option is disabled.
If you select the Enable retry checkbox, you must input values into the following mandatory fields.
• Status Codes — Set status code on which you want the HTTP retries to happen. It can be a comma
separated values of status codes as well as a range of status codes. For example, 302-400,500.
• Number of Retries — Set the number of retries allowed for the trigger. The maximum number of retries
must not exceed 3.
• Retry Interval — Set the interval (ms) between two subsequent retries. The maximum retry timeout
value (Retry Interval * Number of retries) can be configured using MaxHttpRetryTimeoutInMins
shared.property. Default value of MaxHttpRetryTimeoutInMins is 1 min.
• A Document Template to generate the request with an .XML extension
• The target URL to send the HTTP POST request to
• Encoding for selected template: XML, URL, or other
• The Content Type (text/xml by default)
• Up to 5 HTTP headers (names and values)
• Timeout (in ms) for HTTP request
• Check if you want this Trigger to throw an exception if the HTTP return code is out of the range 200-210
indicating success.
You can immediately debug your Trigger by selecting a record to debug against (click the icon). This sends a
generated HTTP POST request to the specified URL and displays results in a popup window.
Note: You must create at least one text-based Document Template before you can use this Trigger.
Important: The HTTP POST Trigger does not add a header or footer to your XML document.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 235
Chapter 6: Adding business logic
Send HTTP get request
This Trigger sends an HTTP GET request to a specified URL. It can be used to send a REST-style request to
a third party. To use this Trigger, select:
• Enable retry checkbox if you want to enable retry options for the trigger. By default, this option is disabled.
If you select the Enable retry checkbox, you must input values into the following mandatory fields.
• Status Codes — Set status code on which you want the HTTP retries to happen. It can be a comma
separated values of status codes as well as a range of status codes. For example, 302-400,500.
• Number of Retries — Set the number of retries allowed for the trigger. The maximum number of retries
must not exceed 3.
• Retry Interval — Set the interval (ms) between two subsequent retries. The maximum retry timeout
value (Retry Interval * Number of retries) can be configured using MaxHttpRetryTimeoutInMins
shared.property. Default value of MaxHttpRetryTimeoutInMins is 1 min.
• An Integration Link field (which includes a dynamically generated destination URL template).
• A timeout (in ms) for the HTTP request
You can immediately debug your Trigger by selecting a record to run it on (click the icon). This sends the HTTP
GET request to the generated URL and displays the results in a popup window.
Result of HTTP GET request is stored in shared variables similar to POST request - see Send HTTP post
request on page 235.
Note: You must create at least one Integration Link field before you can use Triggers of this type.
Send SMS message
This Trigger sends an HTTP request to SMS Gateway server, which sends SMS message to recipient. You
need to have a valid account with SMS service provider to facilitate this service. To use this Trigger, select:
• Enable retry checkbox if you want to enable retry options for the trigger. By default, this option is disabled.
If you select the Enable retry checkbox, you must input values into the following mandatory fields.
• Status Codes — Set status code on which you want the HTTP retries to happen. It can be a comma
separated values of status codes as well as a range of status codes. For example, 302-400,500.
• Number of Retries — Set the number of retries allowed for the trigger. The maximum number of retries
must not exceed 3.
• Retry Interval — Set the interval (ms) between two subsequent retries. The maximum retry timeout
value (Retry Interval * Number of retries) can be configured using MaxHttpRetryTimeoutInMins
shared.property. Default value of MaxHttpRetryTimeoutInMins is 1 min.
• Template for URL used to reach SMS Gateway. This template typically should include:
• Login credentials for your SMS account
• Address of SMS sender
• Phone number of SMS recipient
• Text of SMS message
• Request type: HTTP GET or HTTP POST
• Timeout (in ms) for HTTP request
236 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Triggers and workflows
The following example shows a URL template which reaches to Clickatell SMS Gateway
(https://www.clickatell.com/):
http://api.clickatell.com/http/sendmsg?user={!#SETTINGS.sms_user}&password={!#SETTINGS.sms_password}&
api_id={!#SETTINGS.sms_api_id}&MO=1&from={!#SETTINGS.sms_from}&to={!cell_phone#value}&
text=Your+verification+code+{!ver_code}
Please note:
• SMS credentials (user name, password, API ID, sender's phone number) are stored in Settings object.
Template tokens for these fields are used in URL instead of actual values.
• Template token for recipient's phone number uses #value suffix to remove any formatting.
• Explicitly provided text message must use URL encoding.
• HTTP response will include ID of sent message or error code.
Object Script
Object Script triggers run JavaScript, allowing the manipulation of multiple fields and records in one trigger via
server-side Query API calls. To use this Trigger, enter a formula that returns no value, but invokes one or more
Rollbase API calls (see Server-side API on page 949 for more information). The following example modifies the
amount field of an invoice record and prints a message displayed in the trigger debugger:
rbv_api.setFieldValue("invoice", {!id}, "amount",
{!amount}*(1-{!discount}/100));
rbv_api.print("amount after discount: "+
rbv_api.getFieldValue("invoice", {!id}, "amount"));
Progress recommends that only experienced Rollbase developers use Object Script triggers. See Debugging
complex triggers on page 253 for more information.
You can use all types of JavaScript in Object Script triggers including flow control constructions. To terminate
the flow of Object Script trigger, as well as all subsequent triggers, and to rollback the entire transaction, you
can throw a JavaScript exception:
if (something_is_terribly_wrong)
throw "Cannot perform operation - aborted";
Run Triggers on Related Records
Typically, triggers do not invoke other triggers; however, some triggers offer an explicit option to do so. This
trigger type allows you to explicitly invoke triggers with specified timing options on related records. To use this
trigger, configure the following:
• The relationship between the current object and a target object (if the relationship is multiple, triggers will
be invoked on multiple records).
• Either select a timing option on the target object to determine which triggers to invoke or explicitly select a
group of related triggers to run:
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 237
Chapter 6: Adding business logic
Note: If this trigger is used, Progress highly recommends using the trigger debugger to ensure expected
results. See Debugging complex triggers on page 253.
REST Service trigger
Rollbase enables you to map Rollbase fields to REST service fields and access REST end points with zero
coding. After you map, the code is auto-generated for you.
Note: Rollbase supports JSON REST services only. Also, you will not be able to invoke DELETE operation.
After you select REST service as the trigger type, you will be able to see the new REST service trigger page.
In this page, you must enter the trigger details. See Creating a trigger on page 223 for more information.
The high-level steps to configure a REST Service trigger include:
1. Select the Enable retry checkbox if you want to enable retry options for the trigger. By default, this option
is disabled. If you select the Enable retry checkbox, you must input values into the following mandatory
fields.
• Status Codes — Set status code on which you want the HTTP retries to happen. It can be a comma
separated values of status codes as well as a range of status codes. For example, 302-400,500.
• Number of Retries — Set the number of retries allowed for the trigger. The maximum number of retries
must not exceed 3.
• Retry Interval — Set the interval (ms) between two subsequent retries. The maximum retry timeout
value (Retry Interval * Number of retries) can be configured using MaxHttpRetryTimeoutInMins
shared.property. Default value of MaxHttpRetryTimeoutInMins is 1 min.
2. Provide a base path URL of the Rest Service, to which you want to connect, in the REST Service URL
field.
3. Select the required Http Method. Currently, Rollbase supports GET, POST, and PUT and the default option
is GET.
238 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Triggers and workflows
4. Select the required Authorization type. By default, No Auth selected. Rollbase also supports basic
authentication. When you select Basic Auth option, you need to provide the username and password.
5. Click Configure to configure the Services and Mapping. The Configure REST Service page opens.
6. Optionally customize functions in the trigger formula.
7. Test and Debug the trigger.
How to map a Header
The Header tab allows you to configure header information that you wish to send to the REST endpoint. You
can either pass a value from Rollbase object fields or create a constant key/value pair.
To map the Header:
1. From the New Trigger screen, click Configure. The Configure REST Service screen opens displaying
Rollbase objects and fields on the left and Headers on the right. By default, the Header tab is selected,
allowing you to map fields.
2. Add a mapping pair to the header by using the Add New Mapping Pair icon and to add a constant value
use the Add New Constant Pair icon.
3. To map a field, select a circle next to a Rollbase field and drag the arrow that appears to a circle next to a
Header. Note that you can only map fields and attributes, not objects and entities. See Supported data types
and conversions on page 283 for a complete list of supported data types and conversions.
Note: You can drag and drop the mappings to rearrange it.
4. When you have finished mapping, click Configure URL.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 239
Chapter 6: Adding business logic
When you use a Mapping pair, you can drag a Rollbase field and connect it to a new mapping pair. This adds
a new pair to the header with the key name defaulting to the Rollbase field integration-name (editable) and the
value maps to field token (non-editable).
Constant pairs are fixed (constants) irrespective of the records the trigger executes. These pairs can be used
to represent constant keys.
Note: The preview mapping option is available for all tabs. It hides all unmapped nodes from the tree. This
enables you to focus on the nodes you have mapped and easily verify the mappings. The preview can be
viewed by clicking on the eye icon. Preview mode can be closed by clicking on the crossed eye icon. When in
preview mode, you cannot edit the maps.
Configuring URL
The URL Builder tab allows you to build REST URL path segments with dynamic or constant values.
For example, if you want to build a URL with customerId as path segment, the cutomerId value should be
dynamically replaced from current record on which trigger is executed. You can easily achieve this by using
this URL Builder tab.
You can create a path segment by providing a name and a value (<RESTURL>/customers/{!custId}) or you
can just create a path segment which maps only to a value ( <RESTURL>/{!custId}). The value of path segments
can be mapped from Rollbase fields or created as constant values.
To configure URL:
1. Create new mapping pair and map your REST field to the new mapper.
2. Build the URL where value of the mapped field should be replaced with the record value on which the trigger
must be executed.
3. When you have finished mapping, click Configure Query Param
You can also build an URL with multiple dynamic path segments my creating more mapping pairs.
240 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Triggers and workflows
Configuring Query Parameters
The Request tab allows you to configure data to REST endpoint based on the selected Http Method. Request
tab is called Query Parameters for a GET call and Request Body for POST and PUT calls.
If you select GET as the Http Method, all mappings (both Rollbase field mapping and constants) will be
appended as URL parameters to REST endpoint. Request tabs also allows you to add both Rollbase field
mappings and constants.
If you select " POST" or "PUT" as the Http Method, all mappings will be sent as json object in request body to
endpoint.
If you would like to change json structure, you can customize the generated code to update the structure. See
Overriding generated functions to provide custom behavior on page 244 for more information.
GET Request: This is used to get details from the REST endpoint by mapping the Rollbase fields as new
mapping pairs.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 241
Chapter 6: Adding business logic
PUT and POST: These are used for creating and updating records on REST endpoint. For all PUT and POST
requests, mappings will be sent as json data.
Configuring Response
The Response tab allows you to configure Rest response data into Rollbase object field by creating a response
tree.
The response tree can be created in one of the following ways:
• Using the Invoke REST Service option that enables you to invoke the REST service with the header and
the request you have mapped using an existing record in Rollbase.
242 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Triggers and workflows
• Using the Copy & Paste JSON option and passing a sample Response into a text area.
When you use the Invoke REST Service option, you must:
1. Select record from the drop-down list and invoke a trigger or invoke REST service by either providing inline
values for all your mappings that are done in the Header, Request, and URL builder tabs. The Select
Record drop-down list will list top 10 records from your Rollbase objects.
2. Once the response tree is built, you can add/update/delete more nodes by using toolbar buttons. This is
useful if the schema is incomplete.
3. Select a node under which you want to add a new node.
4. Click the + icon to add a new node. Similarly, you can edit a node and change its datatype by using the edit
icon. You can also delete a node by using delete icon.
Note: At this stage, you can map a node from response object field to Rollbase object field (from right to
left of the tree).
5. Click OK to generate the code. You can then test and debug the trigger.
Note: Response data can be simple json object or have sub-objects returned in a json array. See Supporting
simple and complex cases in Response mapping on page 243 to know how response fields will be mapped to
Rollbase fields.
Supporting simple and complex cases in Response mapping
Response data can be simple json object or have sub-objects returned in a json array. In this section, you will
see how response fields will be mapped to Rollbase fields.
Simple case: For example, if you map REST response fields to Rollbase Base object fields, the REST response
field is mapped from simple Json object, there is a direct 1 to 1 correlation between the REST service data and
the Rollbase Object data.
When the REST response field is mapped to an array of Json object fields, then the first entry is picked from
the array of objects and is mapped to Rollbase Base object.
Complex case: The three available options when you map REST response containing sub-objects to Rollbase
Related objects are:
• Add sub-objects as new record: Enables you to add a new record and attach it to the base object
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 243
Chapter 6: Adding business logic
• Update an existing record: Enables you to map the fields that are used to uniquely identify the related record
in Rollbase existing records.
Note: You can map more than one field that can be compared against REST response. The fields will be
updated only if matched. If multiple mapping is done, all conditions should match to update a record (that
is, an AND condition).
• Update if existing else Add as new: Enables you to update an existing record option. However, if the condition
does not match, it will create a new record in Rollbase related object and attach it to the base object.
Note: When you add REST response sub-object fields to Rollbase related object fields, these options pop-up
while mapping the first sub-object field.
The table below explains the supported levels in response mapping.
Table 1: Supported levels in response mapping
Rollbase REST Response Rollbase REST Response Operation Supported
object Type Relationship action
Base Object - - Update Yes
Object
Base Array - Updates from Update Yes
Object first array item
Related Object 1:1 Uses this object Create,Update, or Yes
Object for operation UpdateElseCreate
Related Array 1:1 Picks first item Create,Update, or Yes
Object from array and UpdateElseCreate
uses it for
operation
Related Object 1:M or M:M Uses this object Create,Update, or Yes
Object for operation UpdateElseCreate
Related Array 1:M or M:M Uses all objects Create,Update, or Yes
Object for operation UpdateElseCreate
You can't map REST response fields from a different level or a same level (from different object) to a single
Rollbase related object. However, you can create another Related object and map fields from different REST
response object.
Overriding generated functions to provide custom behavior
Code for the formula that Rollbase generates is divided into two sections as shown in the screen below.
244 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Triggers and workflows
You should not change any code in the second section, labeled Generated code. If you change request and/or
response mappings, Rollbase regenerates this section of code.
The code in the first section contains function definitions that you can edit to customize processing and formatting.
Rollbase does not regenerate this code when you change mappings.
The functions you can edit and customize include:
• formatDate() — Converts Date fields from Rollbase to a standard format accepted by the Decision
Service. Edit this function to change the format.
• formatDateTime() — Converts DateTime fields from Rollbase to a standard format accepted by the
Decision Service. Edit this function to change the format.
• updateURL(url) — Manipulates the URL before invoking request
• processRestRequestData() — Converts simple JSON object that includes all mappings as properties
of the object for PUT/POST calls.
• processRestResponse() — Updates any record value or persists REST response to some Rollbase
field.
• convertResponseData() — Handles REST response and converts data to corresponding format based
on Rollbase field data type. This ensures that create or update records works.
• beforeStart() — Runs before invoking REST endpoint. REST endpoint URL, headers (if you added
mapping under the header tab), and request data are passed as arguments of this method. If a GET call is
made, the request data parameter is null. This callback method enables you to write any pre-trigger execution
code such as invoking some other trigger or calling any other server-side API.
• afterComplete() — Runs after the REST trigger execution is completed. Response data is passed as
a string and a JSON object. This callback method enables you to write any pre-trigger execution code such
as invoking some other trigger or calling any other server-side API.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 245
Chapter 6: Adding business logic
Example customization
The example below shows how to override the processRestResponse() function to save the response in a field
in the Progress Bedford record:
function processRestResponse(jsonResponseString, jsonResponseObject,
requestDuration, requestStartDate)
{ /* Add post processing to the REST response before writing fields and objects
in Rollbase - by default we leave it untouched. */
// Example saving response to a field: rbv_api.setFieldValue
('ObjectName', '{!id}', 'Trace_Rest_Response', jsonResponseString);
rbv_api.setFieldValue("Building", '{!id}', "Rest_Response", jsonResponseString);
return jsonResponseObject;}
The View page for Progress Bedford includes the response in the configured field:
Example REST trigger mapping
This example calls a REST Service (GET call) that returns weather update. It illustrates how you can map fields
from related objects in the request. The request mapping maps a field from one related object, Weather City
ID, where Building is the base object to update weather for the selected City.
Configuring REST Service Query Parameters
The request mapping maps a field Weather City ID to Request Parameters. Also, creates a constant pair to
map the appid to get the REST response.
246 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Triggers and workflows
Building Response
After the fields are mapped to configure query parameters, the response is configured by invoking the REST
Service. This enables you to build the response by selecting the Rollbase record you want to map to get the
response.
Mapping Response tree
After a response is built, the response tree is generated with all the REST service objects. In this example,
only Humidity is mapped to the Rollbase Outside Humidity field for an update.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 247
Chapter 6: Adding business logic
Result
The example trigger is configured to run after update. The following screen shows the the existing humidity
value for the city, Bedford:
After the record was updated, the following screen shows that the trigger received a response with the value
of the humidity:
248 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Triggers and workflows
Send Email
This trigger sends an email based on an email template. Alternatively, you can select an email template field
to use per record (this provides a way to dynamically determine which email template to use based on a field
value in the record).
Note: You must create at least one email template for a given object definition to create this type of trigger.
See Email templates on page 199 for more information.
Apart from the common trigger settings described above, you must select the recipient email address (and,
optionally, CC and BCC recipients). This can be a specific address (you can use the popup selector to choose
one), or an email address stored in one of the record's fields (use the Use Field helper). You must also select
the email template or email template field to use.
You can also type in text and formula fields which return one or group of (separated by space, comma, or
semicolon) valid email addresses.
You can also specify whether the Reply To field in a trigger-generated email should contain the email address
of the current user, the default auto-reply email address (defined in the Account Settings page), or an explicitly
specified email address.
Unique Fields Combination
This trigger validates that a certain combination of fields is unique across all records. If the combination is not
unique (another record contains the same values for each of the fields specified here), the operation is terminated
and an error message is displayed. To use this trigger, select:
• A combination of fields that must be unique
• The error message to display (e.g., "Author and title combination must be unique")
• Option to ignore fields' combination with null values.
Update Field Value
This trigger updates the value of a field in the current record or a related record using a formula. To use this
trigger, select:
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 249
Chapter 6: Adding business logic
• A record to update: current or related record(s).
• A field to change (depends on the previous selection).
• A formula to calculate the new field's value: See below for expected return types.
Example 1: Update text field with value depending on numeric field:
({!amount} > 1000) ? "Big Order" : "Small Order");
Example 2: Update lookup field with multiple values (use JSON array):
[ 12345, 56789 ]
Note: If this formula evaluates to or returns null, the field's value will not be changed.
In addition, the following options are available when configuring the trigger:
• Access Control Policy — Most trigger types do not check permissions; however, the Update Field Value
trigger (along with the Change Workflow Status on page 233 and Create New Record on page 234 trigger
types) does check update and create permissions for the current user. When configuring a trigger of this
type you can choose what Rollbase should do when access is not allowed:
• Do Nothing: (ignore permissions)
• Skip This Trigger: Do not run the trigger
• Throw Error: This will terminate entire update or create transaction
• Dependent triggers — Most triggers do not result in running other triggers; however, the Update Field Value
trigger (along with the Change Workflow Status on page 233 and Create New Record on page 234 trigger
types) does have the option to run dependent triggers after this one is completed by selecting the Run
dependent triggers after this one is completed check box.
Note: If you use this option, Progress highly recommends using the trigger debugger to ensure expected
results. See Debugging complex triggers on page 253 for information about the trigger debugger.
The formula used in this trigger must return a value that is used to update the selected field on the current or
related record(s). The expected return value depends on the type of the field to be updated as shown in the
table below:
Field Type Expected Value
Text fields String
Numeric fields Number
Checkbox true or false
Process Process ID
Status Status ID or integration code
Single picklist Picklist item ID or integration code
250 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Triggers and workflows
Field Type Expected Value
Multiple picklist Picklist item ID as number or comma-separated string,
with the picklist item's IDs
Lookup Related record ID as number, JSON array of IDs, or
comma-separated string with related records IDs
Template Select Template ID or integration code
Date or Date/Time JavaScript Date object or number of milliseconds as
returned by the JavaScript getTime() function
Time String representing time in user selected format.
Example: 2:05 pm
Validate Record Data
This trigger validates the record's data using an expression. If the expression results in an error (i.e. a non-null
value expected as a string message), the data operation is terminated and an error message is displayed. This
is similar to the situation where a field validation fails when creating or modifying a record. To use this trigger,
provide a formula expression to validate. The formula returns a string error message when validation fails. It
returns an empty string or null if the validation succeeds. For example:
if ({!amount} > 100000)
return "Order is too large: {!amount}";
else
return null;
Another example:
if ("{!email}" == "" && "{!phone}" == "")
return "Either email or phone must be specified";
else
return null;
Note: You can choose the Treat this trigger as a Warning option to allow trigger execution to continue even
if there is an error message. In this case, if validation fails at runtime, the user will have a chance to check an
Ignore Warning checkbox and proceed with saving data despite the warning. This is similar to custom field
validation (see Field validation on page 140).
Example: Set field based on a workflow status change
Consider the following example: The date when a record's workflow status changes to "Closed" should be
captured for reporting purposes. You can accomplish this as follows:
1. Create a workflow status named "Closed" and assign it the integration code "C."
2. Create a Date field for the object named "Closing Date." Only add this field to the view page so it is essentially
treated as a read-only field.
3. Create a workflow action named "Close" that changes the status to "Closed."
4. Create an Update Field Value trigger named "Record Closing Date" with the following configuration:
Timing After Update
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 251
Chapter 6: Adding business logic
On Field Change Workflow Status
Field to Change Closing Date
Change Value Formula "{!status#code}"=="C" ? new Date() : null
As soon as the status is changed to "Closed" (regardless of whether this change was invoked by the workflow
action, manual record editing, another trigger, API call, or other source of change), the current date will be
stored in a the Closing Date field as shown in the screens below.
Before status change:
After changing the status on the edit page:
252 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Triggers and workflows
Debugging complex triggers
When a trigger invokes triggers on related records, it is critical that you use the trigger debugger to ensure
expected results. Use rbv_api.print() API calls to print additional debugging information including field
values and intermediate formula results.
Note: Delayed triggers cannot be debugged in the trigger debugger since the user is absent when they are
running. To debug these triggers consider running them without any delays. See Debugging delayed triggers
on page 255 for details.
To debug a trigger:
1. On the New Trigger or Edit Trigger page, click Debug Formula under the formula.
A selector window opens.
2. Select the record on which to run the trigger.
The debugging window opens and displays three sections: Parsed Formula, Result, and Original Formula.
You can navigate to each section by clicking the section name on the toolbar.
When debugging a Automating business decisions with Corticon rules on page 277, a fourth section, Debug,
is also included. This section displays the Corticon Server URL, the decision service request data, and the
decision service response.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 253
Chapter 6: Adding business logic
The trigger formula debugger cannot execute database transactions. You can use the variable
rbv_debugFormula to conditionalize code that requires a database transaction and debug the rest of the
formula. This variable exists when user invokes the formula in the debugger, but does not exist when running
the actual trigger in the application.
Use the following code pattern to detect both cases. In this example, the function returns without creating a
record if the variable rbv_debugFormula is present and has a value.
function createRBRecord(rbObjectName,recordData,isAttachReq,attachData){
if(this.rbv_debugFormula !== undefined && this.rbv_debugFormula){
rbv_api.println("Skipping create record for "+ rbObjectName);
return;
}
varrecId=rbv_api.createRecord(rbObjectName,recordData);
if(isAttachReq===true && recId){
rbv_api.attach(attachData["relName"],attachData["objName1"],
'{!id}',attachData["objName2"],recId);
}
}
254 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Workflow processes
Debugging delayed triggers
Debugging delayed triggers is challenging because there is no one around when they run. See Delayed and
repeating triggers on page 222 for information about delayed triggers.
The following considerations should be helpful for debugging delayed triggers:
1. Always debug triggers using the trigger debugger before configuring the delay criteria. See Debugging
complex triggers on page 253 for details.
2. Check the trigger queue page by clicking Queue on a record view page to see when the trigger is scheduled
to run.
3. Remember that Object Script on delayed triggers require permissions assigned to the Server API role. For
information on permissions and access control, see Access control on page 647.
4. Progress recommends using Create Audit Trail Record on page 233 triggers for debugging purposes, because
the regular debug window is not available for delayed triggers.
Workflow processes
A workflow process is a container for a group of workflow statuses and actions, moving a record from one
status to another. When the Workflow attribute is first set on an object definition, Rollbase creates one workflow
process named Default. In most cases, all records follow the same workflow and it is sufficient to have only
one workflow process.
In some complex cases, when workflow rules are different for different records, you can define more than one
workflow process. The diagram below illustrates two different processes for an order object: Small Orders and
Large Orders.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 255
Chapter 6: Adding business logic
Workflow overview
To use workflows, you must first enable the Workflow attribute on the desired object definitions. This creates
a default record status named Created and a workflow process you can modify based on your specific needs.
The Workflow attribute is in the Advanced Attribute section of an object definition:
There are three basic workflow concepts:
• Workflow status — Indicates the current state of a record. A current record's status determines the set of
currently available workflow actions.
• Workflow action — An operation that a user can perform on a record. The action can change the status of
a record, invoke one or more triggers, send an email, etc.
• Workflow process — A container for a set of statuses and actions that as a whole make up a particular
workflow
The following diagram illustrates a sample workflow process for handling orders. By defining workflow statuses,
it is possible to trigger actions based on an order's status change.
The following topics describe each component of a workflow in detail.
Creating a workflow process
This topic describes the procedure to create a worklfow process.
Ensure for the following:
• You have Administration privilege to create a new application.
• You have created a new application or installed an available Rollbase application.
• Created an object or select an existing object for the selected application.
256 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Workflow overview
Note: Ensure that in the Object Attributes > Advanced Attribute, the Workflow attribute checkbox is
selected.
From the default status, workflow actions can allow movement of a record into another set of statuses that
implicitly determines how a particular workflow process is designed. You can reorder workflow processes in
the Workflow Processes area of an object definition page to set the order in which they appear in any list.
When you have more than one workflow process defined for an object, you can use a trigger to automatically
assign the appropriate process (the Workflow Process field) to newly created records based on certain criteria
(for example, an order's value). See Update Field Value on page 249 for information about configuring this type
of trigger.
To create a new workflow process:
1. Open the object definition page (see Viewing and editing an Object Definition on page 132).
2. From the ribbon, select Workflow Processes to navigate to the Workflow Processes area of the page.
3. Click New Workflow Process.
4. Specify the Process Name and select a Default Status to be used when this process is assigned to a
particular record. The newly created process will appear in the Workflow Processes area of the object
definition.
To design a workflow process, you must first define workflow actions and workflow statuses that can be a part
of the process. All workflow statuses can participate in any workflow processes. Editing and viewing a workflow
process on page 257 describes how to edit and view your the workflow process.
Editing and viewing a workflow process
The following procedure describes how to edit and view a workflow process:
1. Open the object definition (See Viewing and editing an Object Definition on page 132).
2. From the application view menu, select Workflow Processes to navigate to the Workflow Processes
group box.
3. You can perform the following operations in the Workflow Process group box.
• Click New Workflow Process to create a workflow process from the object definition page.
• Click Reorder to change the display order of the processes in the Workflow Processes group box.
• Click the Edit link of a workflow process to redefine the process.
• Click the Clone link of a workflow process to select and clone an existing workflow process to create a
similar new workflow process.
• Click the Delete link of a workflow process to remove the process.
• Click the View Diagram link of a workflow process to see a visual representation of the Workflow State
Diagram.
• Click the Workflow Designer link of a workflow process to design and view the workflow process in the
workflow designer.
4. Click the name of the workflow process to view it.
The workflow process view screen opens:
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 257
Chapter 6: Adding business logic
5. On this screen, you can do the following:
• Click Edit to redefine the process attributes.
• Click Delete to remove the process from the object.
• Click View Diagram to see a visual representation of the Workflow statuses included in the process.
• Click New Workflow Status to create a new workflow status for the process.
Working with the Workflow Designer
This topic provides an overview of the Workflow Designer.
Rollbase now comes equipped with a new graphical drag-and-drop interface to visually create and maintain
the workflow processes for an object. The new Workflow Designer’s intuitive interface allows you to define your
workflow processes with ease. It adds greater clarity around how you want to map your process steps through
visual representation like a flowchart. It shows statuses as boxed labels, transitions as lines connecting the
statuses, and actions as the underlying conditions for the transition.
The Workflow Designer is fully compatible with the Rollbase prior 5.0 versions workflows, statuses and actions
so that you can continue to edit and maintain your workflow processes as usual. The workflow process is
automatically saved when you close the Workflow Designer.
Here’s a sample view of a workflow process designed using the Workflow Designer canvas.
258 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Workflow overview
Workflow Designer Interface
This topic describes the various components, fields and actions activities that comprise the Workflow Designer
interface.
Workflow Canvas
The Workflow Designer’s canvas is the place where you will perform the following activities to create your
workflow process.
• Design and rename a workflow process
• Add new or use existing statuses
• Connect statuses
• Add new or associate existing actions to the workflow process
• Show or hide the actions label
• Move, resize and delete statuses and actions
• Perform actions using the Canvas Toolbar options
• Zoom and pan a workflow process
• Close the workflow designer
Statuses panel
The Statuses panel contents are hidden from the view by default, to provide more space for the canvas. The
panel allows you to drag statuses and use those in a workflow process.
Here’s a sample view of how a status appears on the canvas in different states.
Note: You can re-position a status by selecting and dragging it across the canvas and re-size it by selecting
and dragging its connector nodes.
State Visual Status
Unsaved Status - Default
Unsaved/Saved - Unconnected Status -Hover
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 259
Chapter 6: Adding business logic
State Visual Status
Unsaved/Saved - Unconnected Status -
Selection
Saved Unconnected Status - Default
Saved Connected Status
Saved Default - Connected Status
Action Label – Show/Hide
As the name indicates, Action Label - Show/Hide allows you to show/hide the actions label from the workflow
process diagram. This helps to save space and visualize your statuses better. By default, the Action Label will
be shown. An action connector line is automatically created when you connect two saved statuses. An Action
pop up appears displaying the list of all existing actions if available for the target status, when two statuses are
connected. This helps you to change the status to the target status. When there are no existing actions, the
Actions pop up will be populated only with an Add New Action icon.
Note: You can re-position an action by selecting and dragging it across the canvas and re-size it by selecting
and dragging its connector nodes.
Here’s a sample view of the Action Labelthat shows existing actions for the target
u
.sa
tts
260 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Workflow overview
Here’s a sample view of how an action appears on the canvas in different states.
State Action
Unsaved Action - Default
Unsaved Action -
Selection
Saved Action - Default
Saved Action - Selection
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 261
Chapter 6: Adding business logic
Canvas Toolbar options
Use the icons in the Canvas Toolbar to perform the following activities to design a workflow process:
Icon Icon Name Description/Result
Add New Status You can drag a status anywhere on the canvas and rename it. To
remove a status from the canvas, click Add New Status again or
select the status and press the DELETE key.
Layouts You can choose to preview a preferred layout and apply it for the
workflow process to retain the position of the statuses.
Note:
• Applying a selected layout will override the existing layout.
• When an existing application is imported, the default layout of
a workflow process in the Workflow Designer appears in a ‘Left
to Right Layout’.
Save as PNG Downloads the workflow process diagram to your system and
saves it as a .PNG file.
Fit diagram to Fits the workflow process size to the canvas. If the workflow
available space process size is large, this will shrink and fit it to the canvas.
Zoom In Magnifies the workflow process to make it appear much larger
and clearer.
Note: Click in the white space on the canvas and drag the mouse
to pan and view the entire diagram when a workflow process
image is magnified.
Restore zoom level Restores the original size of the workflow process.
to default
Zoom Out Reduces or alters the size of the workflow process.
Here’s a sample view of the Layouts:
262 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Workflow overview
Designing a Workflow Process
This topic describes the procedure to design a workflow process using the Workflow Design.
Pre-requisite: Create a workflow process.
Perform the following steps to design a workflow process:
1. In the Object Definition page, go to the Workflow Processes group box, select a workflow process and
click the Workflow Designer link associated with it. The Workflow Designer window appears.
2. Add a status, to the workflow process. See adding a workflow status from the workflow designer for detailed
steps.
3. Click Add New Action to create a new action.
The New Action panel appears. See adding a workflow action from the workflow designer for detailed
steps.
4. On the Workflow Designer toolbar, click the process name and rename it, if needed. Alternatively, hover
the mouse on the process name to view and click the edit icon. Rename the process and press ENTER.
To cancel renaming the process, press ESC.
You have successfully designed a workflow process.
5. Click Close to close and exit from the Workflow Designer. The workflow process is saved.
To delete a workflow process, go to the Object Definition page -> Workflow Processes group box, select
a workflow process and click Del. Refer Step 3 of Editing and viewing a workflow process to see all the
operations that you can perform in the Workflow Processes group box.
Adding a Workflow Status from the Workflow Designer
This topic describes the procedure to add a workflow status to the workflow process from the workflow designer.
Pre-requisite: Select a workflow process from Object Definition > Workflow Processes group box and click
the Workflow Designer link associated with it..
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 263
Chapter 6: Adding business logic
To add a status, perform the following steps:
1. To add a status from the Workflow Designer, do any one of the following:
• From the Statuses panel:
1. Click the Statuses panel to expand it.
2. Click the Add icon to add a status to the workflow process. A text box appears with a Tick mark icon.
3. Enter the Status Name and click the Tick mark icon. A new status is created and it appears in the
Statuses panel.
Note: The Statuses panel displays only existing statuses that are not in use in the workflow process.
Drag statuses from the Statuses panel to use it in the workflow process.
• From the Canvas Toolbar:
1. In the Canvas Toolbar, click the Add icon . A new unsaved status is added to the canvas.
2. Select a status in the workflow process to view and edit its properties under Action Label > Edit
Status. Edit the Status Name, Integration Code and enable the Set As Default checkbox, as
needed and Save. A new status is created and added to the workflow process in the Workflow
Designer canvas.
Note:
Double-click a status in the workflow designer to rename it. Refresh the object definition page to view
updated statuses whenever you create a status in the workflow designer.
See Workflow status to add a workflow status from the Object Definition page.
2. To remove a status from the designer, select the status and press DELETE. Deleting a status will un-assign
all assigned actions to it. This action only removes the status from the workflow process but it does not
delete any status from the Rollbase.
3. Click on a status’ connector node, hold and drag the mouse cursor to another status’ connector node to
connect the two statuses.
The Actions pop up appears prompting to Add New Action.
See adding a workflow action from the workflow designer for detailed steps.
Workflow status
A status represents the current state of a record. Statuses are similar to picklist values, with a special meaning
in workflow. To define a new workflow status, you specify:
• Status Name — The display name of the workflow status (required)
• Integration Code — The integration code used in APIs
• Whether or not you want to automatically create a new corresponding workflow action to enable moving
records into this new status. You can also provide a name for that new action (defaults to the status name).
• For each workflow process associated with the object, the workflow actions that will be available when a
record has that workflow status.
264 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Workflow overview
When you enable the Workflow attribute on an object, the system generates one default status named Created.
You can change the name of this status if desired. You can then add other statuses as needed. Statuses can
be assigned through workflow actions or explicitly by editing an object record. When editing an object record,
statuses are presented in sequential order. You can define this order by clicking Reorder in the Workflow
Statuses section of an object definition screen.
Adding a Workflow Action from the Workflow Designer
This topic describes the procedure to add a workflow action to a workflow process from the workflow designer.
Pre-requisite: See adding a workflow status from the workflow designer.
Workflow actions allow transition of a record from the default status to another status to bring a workflow process
to a logical conclusion. To add a workflow action from the workflow designer, perform the following steps:
1. Click Add New Action to create a new action.
The New Action panel appears.
Note: A list of available actions for the target status appear when editing an existing workflow process.
2. Enter the Action Name and select or add required properties. See workflow action interface for detailed
steps.
Double- click the action connector node to rename an action. The action name is highlighted. Enter a new
name for the action. A confirmation message appears indicating that the action has been updated
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 265
Chapter 6: Adding business logic
3. Save the new action.
A confirmation message appears indicating that the action has been created.
4. To remove an action from the workflow designer, select the action and press DELETE. A Remove
Confirmation dialog appears for a valid saved action to ensure that an action is not removed accidentally.
This operation removes a workflow action from the workflow process but does not delete any workflow
action from Rollbase.
5. Click OK if this is not an accidental action removal. Alternatively, click Cancel.
Deleting an action removes assigned actions from the target status of the current deleted action.
See designing a workflow process.
Workflow Action Interface
This topic describes the various fileds and actions associated with the workflow actions in the Workflow Designer.
When you select Show, the workflow Action Label interface displays fields specific to the workflow action type
and is segmented into General and Permissions tabs in the Workflow Designer as described below.
General tab - Fields Description
Action Enter a name for the workflow action. Status of the
workflow process changes when this action is
executed.
Render Button Check to render this action as a button (instead of an
item in the action menu) on a record view page.
Group Action Select this checkbox to perform this action for a group
of records.
Use Web Page A new page to create a record of the selected type
(this page will open when the action is performed).
This will be the page the user is taken to when the
action is performed.
Select a web page for the action.
Select Triggers to Run After This Action Select the triggers to run and specify the order in which
you want to run them.
Triggers Displays the list of selected triggers in an ascending
order.
Select Displays the list of available triggers for the selected
action and allows to search for available triggers.
Permissions tab - Fields Description
Set Permissions This field displays a list of all available users for this
action. Select user(s) who can perform this action.
Workflow actions
A workflow action represents a manual action such as a click or a selection that changes a record's status,
sends an email, invokes a trigger, etc. Rollbase supports several types of actions as described in the following
sections.
266 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Workflow overview
When you configure a workflow status, you specify which workflow actions are available for records with that
status. See Workflow status on page 264 for details.
Access to workflow actions can be limited only to certain roles or users. For more information about access
control, see Access control on page 647.
Workflow actions on application pages
By default, workflow actions appear in the actions menu on a record view page:
You can configure a workflow action to appear as a button instead of in the actions menu:
The read-only field Workflow Actions renders links to available actions. This field can be added to record
view pages and as a column in list views:
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 267
Chapter 6: Adding business logic
268 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Workflow overview
You can reorder workflow actions to set the order in which they appear in any list. To reorder workflow actions,
navigate to the Workflow Actions area on an object definition page and click Reorder. Use the arrows to
reorder the actions.
Group workflow actions
If you enable group actions for a particular workflow action, that action becomes available for a group of selected
records in list views by selecting the action from the group actions menu:
If a group workflow action has formula-based condition, selected records will be filtered using that condition.
Status Change action
This action changes the workflow status of the current record. You can create any number of Status pages
and use them for different workflow actions. You can place any editable field from the object definition on these
pages. This allows you to record various information at the time of a user-driven status change.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 269
Chapter 6: Adding business logic
To create this action, select:
• Action Name — The display name of the action
• Group Action — Check to allow this action to be performed on group of records selected in a list view
• Render Button — Check to render this action as a button (instead of an item in the action menu) on a
record view page
Note: If you choose this option, the Toolbar Responsive Overflow Rule drop-down list is enabled. See
Using buttons on pages on page 393 for more information.
• Change Status To — The new workflow status assigned as a result of the action
• Use Web Page — The page of type Status to open when changing the status (this allows presenting fields
for the user to enter or edit upon a status change) Alternatively, you can choose to run this action without
using a Status page, in one click.
• Triggers to Run — You can select deployed triggers to run when this action is completed.
• Action Condition Formula — A formula that returns true or false. If the formula returns false, this action
is not available for the current record.
• Permissions — Specify the role, user, or relationship-based permissions required to run this action. See
Access control on page 647 for information about permissions.
Related Record action
This action creates a related record of the selected type using either a conversion map or a record template.
The action can either create a record of a different object type or clone the current record. To create this type
of action, select:
270 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Workflow overview
• Action Name — The display name of the action
• Group Action — Check to allow this action to be performed on group of records selected in a list view
• Render Button — Check to render this action as a button (instead of an item in the action menu) on a
record view page
Note: If you choose this option, the Toolbar Responsive Overflow Rule drop-down list is enabled. See
Using buttons on pages on page 393 for more information.
• Change Status To — The new workflow status assigned as a result of the action (optional)
• Use Web Page — A New page to create a record of the selected type (this page will open when the action
is performed)
• Use Conversion Map — A conversion map to transfer fields from original record to the new one. For
information about conversion maps, see Converting records on page 160.
• Use Record Template — A record template to create a new record (ignored if a conversion map is selected)
• Action Condition Formula — A formula that returns true or false. If the formula returns false, this action
is not available for the current record.
• Permissions — Specify the role, user, or relationship-based permissions required to run this action. See
Access control on page 647 for information about permissions.
Send Email action
This action sends a template-based email using data from the current record. This action is only available if at
least one email template exists for the current object.
By default, when a user selects a Send Email workflow action, a new page opens that allows the user to edit
the email. To configure a one-click email action, where the default email is sent without opening a new page,
select the Perform action without opening a new page option described below.
To create this action, specify the following options:
• Action Name — The display name of the action
• Group Action — Check to allow this action to be performed on group of records selected in a list view
• Render Button — Check to render this action as a button (instead of an item in the action menu) on a
record view page
Note: If you choose this option, the Toolbar Responsive Overflow Rule drop-down list is enabled. See
Using buttons on pages on page 393 for more information.
• Change Status To — The new workflow status assigned as a result of the action (optional)
• Perform action without opening a new page — When selected, clicking this action sends an email
immediately without opening a new page.
• Reply To — The reply-to email address. You can select the current user's email address, the default email
address (Default Email Sender in account settings) , or type an email address in the text field.
• Send To — The destination email address or addresses. You can select email address fields from the
current record or from related records from the Use Field picklist.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 271
Chapter 6: Adding business logic
• CC and BCC — Optional CC and BCC email addresses
• Email Template — The email template to use. If an email template picklist field is defined for this object,
you can alternatively select the field from the or Template Picklist picklist.
• Triggers to Run — You can select deployed triggers to run when this action is completed.
Note: For any email address field, you can also type in text and formula fields which return valid email addresses.
Template Document action
This action generates a template-based document using data from the current record and presents this document
to the user in a popup window. When used as a group action (see below), this action will merge documents
from all selected records into one. This action is only available if at least one document template exists for the
current object.
To create this action, select:
• Action Name — The display name of the action
• Group Action — Check to allow this action to be performed on group of records selected in a list view
• Change Status To — The new workflow status assigned as a result of the action (optional)
• Document Template — The document template to use. If document template picklist field is defined for
this object, you can alternatively select the field from the or Template Picklist picklist.
• Triggers to Run — You can select deployed triggers to run when this action is completed.
• Action Condition Formula — A formula that returns true or false. If the formula returns false, this action
is not available for the current record.
• Permissions — Specify the role, user, or relationship-based permissions required to run this action. See
Access control on page 647 for information about permissions.
Run Triggers action
This action runs a group of selected triggers on the current record. This action is only available if at least one
trigger exists for the current object.
To create this action, select:
• Action Name — The display name of the action
• Group Action — Check to allow this action to be performed on group of records selected in a list view
• Render Button — Check to render this action as a button (instead of an item in the action menu) on a
record view page
Note: If you choose this option, the Toolbar Responsive Overflow Rule drop-down list is enabled. See
Using buttons on pages on page 393 for more information.
• Change Status To — The new workflow status assigned as a result of the action (optional)
• Use Web Page — Select Standard "Run Triggers" page if you want this action to open a run triggers
page. Select None if the action should be performed without opening new page.
• Triggers to Run — Select the triggers to run and specify the order in which you want to run them.
272 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Workflow overview
• Action Condition Formula — A formula that returns true or false. If the formula returns false, this action
is not available for the current record.
• Permissions — Specify the role, user, or relationship-based permissions required to run this action. See
Access control on page 647 for information about permissions.
Approvals
An approval process is a special type of process in which the process must be approved by a specified group
of users. To create an approval process, you must install the Approvals application. An approval process starts
when a workflow action is run on a particular record and ends when the record is approved or rejected. Rollbase
provides a default implementation for this process that you can customize.
To configure an approval process, follow these steps:
1. Install the Approvals application on page 273
2. Create an email template on page 273
3. Select approvers on page 273
4. Set the Approval attribute on page 273
5. Set up the Approval process on page 274
6. Optionally, customize the approvals process on page 274
Install the Approvals application
Install the Approvals application from the Marketplace (click Install Applications from the Rollbase menu or
from the left sidebar on a setup page). This application has a system object named Approval. Each approval
record contains the following information:
• A reference to the record being approved
• A reference to the user being asked to approve or reject that record (approver)
• The current status of this approval: pending, approved, or rejected
Create an email template
Create an email template to be used to notify approvers that they have something to approve or reject. See
Email templates on page 199 for details. The email template should include a link to the record being approved.
Select approvers
Next, select a group of users who will participate in the approval process. Make sure the Is Approver check
box is selected for each of these users in the edit user page (if you do not see this box, use the page editor to
add it to the page. See Pages, the page editor, and grid controls on page 362 for more information).
Set the Approval attribute
Edit the object you want to participate in the approval process and enable the Approval attribute. This
automatically enables the Workflow attribute if it was not previously enabled. This creates the following
components:
• The system statuses: Approval In Progress, Approved and Declined
• The workflow action object_name Approval (for example, Order Approval), which is used to start an
approval process on a particular record
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 273
Chapter 6: Adding business logic
Note: If you want more than one object to participate in approval process, enable the Approval attribute on
each object.
Set up the Approval process
Edit this object_name Approval workflow action to complete the configuration of the approval process:
• Assign the object_name Approval action to a workflow status. Typically, this is the default status for your
workflow process.
• Select a default list of approvers (this can be changed at runtime whenever the approval process is started
on a record).
• Select an email template to be used to notify approvers that they have something to approve or reject. See
Create an email template on page 273.
• Choose the workflow process in which to use this approval action (typically the Default workflow process).
• Choose the approval type:
• Sequential — Approvers will be notified in sequence. The record will be rejected if any approvers reject
it, otherwise it will be approved once all approvers approve it.
• Parallel — All approvers will be notified simultaneously and can submit their feedback in arbitrary order.
The record will be rejected if one or more approvers rejects it, otherwise it will be approved.
• Tally Votes — This works identically to the parallel approval process, but will continue until all approvers
approve or reject the record. The record will be approved if a majority of the approvers approve it and it
will be rejected otherwise.
• Assign appropriate permissions to run the object_name Approval action.
Optionally, customize the approvals process
To further customize an approval process, you can:
• Create several workflow processes
• Create (by cloning) several object_name Approval actions to start them.
• Create several email templates as needed.
Once configured, your approval processes will operate as follows:
• Any user with sufficient permissions can invoke the object_name Approval action for a selected record
(or a number of records if the Group Action property is enabled for the action).
• An email to the first approver will be sent (or all approvers for a parallel or tally votes process).
• The email should include a link to the record being approved. This link will open the view page for the
approval.
• Approvers will also see a list of records currently waiting for their approval in the My Approvals tab of the
Approvals application. Selecting a record opens the view page for the approval.
274 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Workflow overview
• After reviewing a record submitted for approval, the approver clicks Approve Or Reject, which opens the
approval page:
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 275
Chapter 6: Adding business logic
• On this page, the user can:
• Provide comments.
• Click Approve, Reject, or Cancel.
• If the record is approved, the sequential process will continue and an email will be sent to the next approver
in the sequence.
• If the record is rejected, the approval process will end and the record will be moved to the Rejected status
(any approver has veto power, except for the Tally Votes process described above. That is, an approver
can approve a rejected order or reject an approved order).
• When all approvers have approved the record, it is moved to Approved status.
You can associate triggers to run when a record's status is changed to the Approved or Rejected status. It is
common to configure a trigger to notify specific users when a record has been approved or rejected.
Record queues
A record queue is a type of workflow process specifically tailored for situations in which a queue of records of
a certain type need to be processed by a specific group of users. Rollbase automatically creates this workflow
process when you add the Queue attribute to an object definition. The Queue attribute will enable the Workflow
attribute if it is not already enabled.
When you enable the Queue attribute on your object definition, Rollbase will create the following:
276 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Automating business decisions with Corticon rules
• Two new workflow statuses: In Queue and In Process. The former is assigned by default to the first workflow
process of your object.
• A relationship between this object and the user object (if not already created).
• A new workflow action named Start Processing with a status change page (more details below). This page
assigns the current user to the record being updated. The Start Processing action is available for the In
Queue status and can be used for one record or a group of records. After the user selects the Contact
Owner user on the status change page and clicks Save, the record's workflow status is changed to In
Process.
• A view named In Queue, which shows only records in the In Queue status in the order that they were
created.
With these components in place, the workflow process works as follows:
• New records are created and placed in the In Queue status.
• Any user who has permission to access these records and the Start Processing workflow action can invoke
this action on one or more records.
• The selected user's name will be associated with the record(s) and the status of each record will be changed
to In Process.
Note: You can further modify the Start Processing action and make the entire workflow more sophisticated
by adding more steps to emulate your business process. The Queue attribute helps you start building such a
process with minimal effort.
Automating business decisions with Corticon rules
Progress Corticon is a Business Rules Management System with a patented rules engine that enables you to
automate sophisticated decisions without writing code. To add these capabilities to your app, use a Corticon
Decision Service trigger. The trigger sends application data in a request. The Decision Service uses the
request values as input to its rules and sends the results back to the trigger. You can configure the results to
be mapped into existing and/or new Rollbase records.
For example, a trigger might send information about an insurance applicant — such as age, gender, and health
history — to a Decision Service configured with complex rules defining cost and coverage. The Decision Service
could return a quote along with information that explains the decision.
To configure a Corticon Decision Service trigger, you need the following:
• Access to a Decision Service compiled on and deployed using Corticon server version 5.6 or later.
• An understanding of the data expected by the Decision Service and expected results.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 277
Chapter 6: Adding business logic
When configuring a trigger to invoke a Decision Service, you use a visual mappper to associate fields from
Rollbase objects with attributes and messages of Corticon entities. The Decision Service generates messages
to communicate the results of rule execution. You can map object fields to entity attributes and messages of
compatible data types or data types for which Rollbase can provide conversion. The visual mapper indicates
the data type next to object and entity fields, as shown below, where age is an integer and gender is text.
You can map fields from the object on which the trigger is defined and from objects directly related to it. For
example, if a trigger belongs to object A and object A has a relationship with object B, while object B has a
relationship with object C, you can map fields from A and B — but not from C, as illustrated below. The same
rule applies to Corticon entities.
The trigger supports mappings between related objects and entities with "to-many" cardinalities. When multiple
related records and entities exist on both sides, the trigger handles them in the request and response. If the
cardinality of the relationship for mapped items does not match, the trigger limits the scope of recursion. For
example, if a field in an object with many records is mapped to an attribute in an entity with a cardinality of one,
the trigger sends only the values from the first related record in the request. Likewise, on the decision service
side. When a mapping exists from an entity or message with a to-many association cardinality to a field in an
object with a cardinality of one, only the response or message from the first matching entity will be returned.
See Supported relationships for request mapping on page 280 and Supported relationships for response mapping
on page 281 for details.
Rollbase relationship and Corticon association cardinality notation displays in the mapping tool as follows:
• (*) — Indicates a multiple relationship with the base object or base entity
• (1) — Indicates a single relationship with the base object or base entity
278 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Automating business decisions with Corticon rules
The following screen shows the cardinality notation of the relationships between Car and Message and Car
to Person:
See the following topics for detailed information about how relationships and cardinality affect mapping:
• Supported relationships for request mapping on page 280
• Supported relationships for response mapping on page 281
The visual mapper allows you to filter entities in its tree structure so that you can focus on the items of interest.
You can select different sets of entities to display in the request mapping and in the response mapping. If no
entities are selected, the tree structure displays all entities in the Decision Service. Filtering has no effect on
the mappings. Although they disappear when filtered out, just remove the filter to view them again.
Rollbase generates the trigger formula to access the Corticon Decision Service and handle the response. A
portion of the formula contains methods that you can override to provide custom functionality. For example,
you might want to insert logic in the generated trigger code to capture information about the Decision Service
and save it as Rollbase data. Information such as time when a Decision Service was invoked, the request data,
and the response data could be useful when debugging or to review events that occurred during normal
operation.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 279
Chapter 6: Adding business logic
See the following topics for more information:
• Supported relationships for request mapping on page 280
• Supported relationships for response mapping on page 281
• Supported data types and conversions on page 283
• Creating a Corticon Decision Service Trigger on page 286
• Overriding functions to provide custom behavior on page 292
• Example trigger mapping to related objects on page 294
• Example trigger mapping where response creates a record on page 296
Supported relationships for request mapping
The following table describes supported mappings between Rollbase object fields and Corticon entities attributes
and messages for different relationship cardinalities. In the table, Base object/Base entity is the top-level
object/entity in the tree structure and Related objects/Associated entity is an object/entity with which the
base object or entity has a relationship.
Rollbase object Corticon entities Rollbase relationship Corticon Supported
relationship
Base object Base entity N/A N/A Yes
Base object Associated entity N/A 1:1 or 1:M No
Related object Base entity 1:1 N/A Yes
Related object Base entity 1:M or M:M (Sends first N/A Yes
related record value)
Related object Associated entity 1:1 1:1 Yes
Related object Associated entity 1:M or M:M 1:M Yes
Related object Associated entity 1:M or M:M ( Sends first 1:1 Yes
related record value)
280 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Automating business decisions with Corticon rules
For mappings that involve relationships with multiple records on the Rollbase side single entities on the Corticon
side, when the trigger executes, only values from the first related record will be sent in the request. For example,
the following request mapping maps a field from the related object Order Line to the base entity Item. The
relationship from Order to Order Line is one-to-many, so Rollbase only maps the value from the first Order
Line record as described in the fourth row of the table.
Supported relationships for response mapping
The following table describes where response mapping is supported based on the existence and types of
relationships between Corticon entities and between Rollbase objects. In the table, Base entity/Base object
is the top-level object/entity in the tree structure and Associated entity/Related object is an entity/object with
which the base entity or object has a relationship. Messages are Corticon messages posted by the decision
service to relay information about the result of the service execution.
Response mapping can update and create Rollbase records. The Operation column of the table shows the
operation(s) for each use case.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 281
Chapter 6: Adding business logic
Rollbase Corticon Rollbase Corticon Operation Supported
object entities relationship relationship
Base object Base entity N/A N/A Update Yes
Base object Associated N/A 1:1 Update Yes
entity
Base object Associated N/A 1:M (Update from Update Yes
entity first matching
response)
Related object Associated 1:1 or 1:M N/A N/A No
entity or M:M
Related object Associated 1:1 1:1 Create/Update/UpdateElseCreate Yes
entity
Related object Associated 1:M or M:M 1:M or 1:1 Create/Update/UpdateElseCreate Yes
entity
Related object Associated 1:1 1:M (Returns the Create/Update/UpdateElseCreate Yes
entity first matching
response)
Base object Messages N/A 1:M (Returns the Update Yes
first matching
message)
Related object Messages 1:1 1:M (Returns the Create Yes
first matching
message)
Related object Messages 1:M or M:M 1:M Create Yes
282 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Automating business decisions with Corticon rules
For mappings that involve many entities or messages on the Corticon side but only one record on the Rollbase
side, the response contains only the first matching response or message. For example, the following response
mapping maps a field from messages resulting from the decision service execution to a field in the Rollbase
Message object. Because the relationship from Applicant to Message is one-to-many in both Corticon and
Rollbase, running the decision service can create multiple Message records as described in the last row of the
table.
Supported data types and conversions
You can map a field of a supported data type to an attribute or message of the same type or for which Rollbase
provides an automatic conversion. In request mappings only, you can use Expression and Formula fields that
evaluate to any of the supported data types. In response mappings, you cannot use Formula fields, Expression
fields, or any other read-only fields. These fields include system fields such as createdBy, createdAt, updatedBy,
and updatedAt. In response mappings, if a date field is not compatible with Rollbase formats, you can convert
the date.
See the following sections for more information:
• Supported data types on page 284
• Data type conversions on page 284
• Supported Date and Date/Time formats on page 284
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 283
Chapter 6: Adding business logic
Supported data types
Mappings between Rollbase and Corticon, support the following data types:
• String
• Boolean
• Integer
• Decimal
• Date and Date/Time (in formats supported by Rollbase, see Supported Date and Date/Time formats on
page 284)
Data type conversions
If there is a data type mismatch between a Rollbase field and a Corticon field, Rollbase performs the following
type conversions automatically for both request and response mappings:
Rollbase data type Corticon data type
String Any data type
Any data type String
Date Date/Time
Date/Time Date
Decimal Integer
Integer Decimal
When there is a type conversion, the mapping tool displays nodes in orange and displays conversion type text
when the map is selected. The following screen shows a map with a type conversion from Date to Date/Time.
Supported Date and Date/Time formats
When mapping the data service response to Rollbase Date or Date/Time fields, the value must be in one of
the formats supported by Rollbase. If the format in the response is not supported, you can edit the generated
formula convertResponseData() method to convert the value to a JavaScript Date object. The following
example shows where you can edit the code:
function convertResponseData(value,type,isRbPickList,rbFieldName,rbObjectName){
if(!type || !value) return value;
if(isRbPickList === true){
returnformatPickListValue(rbObjectName,rbFieldName,value);
}
if(type === 'Date'|| type=== 'DateTime'){
284 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Automating business decisions with Corticon rules
//Write your own logic to convert Corticon response to JavaScript Date object
//if the response doesn't match a supported date or Date/Time format.
return newDate(value);
}
else if(type ==='Integer'){
return Number(value);
}
else if(type ==='Boolean'){
return((value==='true' || value===true)?true:false)
}
return value
}
See Overriding functions to provide custom behavior on page 292 for more information about editing the trigger
formula.
Supported Date formats include:
• YYYY/MM/DD
• MM/DD/YYYY
• MMM d, yyyy
• MMMMM d, yyyy
• yyyy/M/d
• M/d/yyyy
Supported Date/Time formats include:
• YYYY/MM/DD h:mm:ss a
• MM/DD/YYYY h:mm:ss a
• MMM d, yyyy h:mm:ss a
• MMMMM d, yyyy h:mm:ss a
• yyyy/M/d h:mm:ss a
• M/d/yyyy h:mm:ss a
• MM/dd/yyyy H:mm:ss
• yyyy/MM/dd H:mm:ss
• M/d/yyyy H:mm:ss
• yyyy/M/d H:mm:ss
• MMM d, yyyy H:mm:ss
• MMMMM d, yyyy H:mm:ss
• MM/dd/yyyy HH:mm:ss
• yyyy/MM/dd HH:mm:ss
• M/d/yyyy HH:mm:ss
• yyyy/M/d HH:mm:ss
• MMM d, yyyy HH:mm:ss
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 285
Chapter 6: Adding business logic
• MMMMM d, yyyy HH:mm:ss
• MM/dd/yyyy hh:mm:ss a
• M/d/yyyy hh:mm:ss a
• yyyy/MM/dd hh:mm:ss a
• yyyy/M/d hh:mm:ss a
• MMM d, yyyy hh:mm:ss a;
• MMMMM d, yyyy hh:mm:ss a;
Creating a Corticon Decision Service Trigger
The high-level steps to configure a Corticon Decision Service trigger include:
1. Configure Rollbase to access a Corticon Server instance hosting deployed decision services. See Configuring
Rollbase to access Corticon Server on page 287 for details.
2. Create the trigger as described in Creating a trigger on page 223, selecting Corticon Decision Service as
the trigger type.
• Choose the decision service to invoke.
• Map the decision service request and response. Before you start mapping, you should understand the
supported data types and conversions, and how relationships affect mapping. See the following topics
for more information:
• Supported data types and conversions on page 283
• Supported relationships for request mapping on page 280
• Supported relationships for response mapping on page 281
3. Optionally customize functions in the trigger formula.
4. Test and Debug the trigger.
See the following topics for examples of Corticon Decision Service triggers:
• Example trigger mapping to related objects on page 294 illustrates request mapping from multiple Rollbase
objects.
• Example trigger mapping where response creates a record on page 296 illustrates response mapping that
creates new Rollbase records.
286 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Automating business decisions with Corticon rules
Configuring Rollbase to access Corticon Server
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 287
Chapter 6: Adding business logic
Rollbase communicates with a Decision Service using REST. You can provide the URL and credentials for the
Corticon Server for all triggers in an application or for a specific trigger:
• Use application settings to configure access for all triggers in an application. You can specify different URLs
for development, staging, and production servers and switch between instances. Rollbase uses the server
you select until you change the settings. Access application settings from the Application Switcher menu.
See Editing applications for details.
• Select the Enable retry checkbox if you want to enable retry options for the trigger. By default, this option
is disabled. If you select the Enable retry checkbox, you must input values into the following mandatory
fields.
• Status Codes — Set status code on which you want the HTTP retries to happen. It can be a comma
separated values of status codes as well as a range of status codes. For example, 302-400,500.
• Number of Retries — Set the number of retries allowed for the trigger. The maximum number of retries
must not exceed 3.
• Retry Interval — Set the interval (ms) between two subsequent retries. The maximum retry timeout
value (Retry Interval * Number of retries) can be configured using MaxHttpRetryTimeoutInMins
shared.property. Default value of MaxHttpRetryTimeoutInMins is 1 min.
• Provide a URL in trigger configuration. When configuring the trigger, specify the Corticon Server URL, the
User Name, and the Password as shown below. You cannot configure the connection in the trigger if the
application settings exist.
288 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Automating business decisions with Corticon rules
How to map a request
To map the Decision Service request:
1. From the New Trigger screen, click Configure in the Corticon Configuration area.
Note: You must configure acces to one or more Corticon Servers before performing this step. See
Configuring Rollbase to access Corticon Server on page 287 for details.
The mapping tool opens and displays a list of Decision Services available on the configured Corticon Server.
2. Select the Decision Service you want to invoke from the list of services. To locate the service, click the filter
button next to Service Name, Major Version, or Minor Version and enter a filter condition.
3. After selecting the service, click Next.
The Input/Output mappings screen opens, displaying Rollbase objects and fields on the left and Corticon
entities, and attributes on the right. By default, the Request tab is selected, allowing you to map fields for
the request.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 289
Chapter 6: Adding business logic
4. Optionally filter the list of Corticon entities by clicking the filter icon next to Corticon Object and selecting
the entities required for the mapping.
5. To map a field, select a circle next to a Rollbase field and drag the arrow that appears to a circle next to a
Corticon attribute. Note that you can only map fields and attributes, not objects and entities.
As you drag the arrow, the circles next to the Corticon attributes change color, indicating the data types are
compatible. Attributes that do not require conversion display green circles and fields that require conversion
display orange circles as shown below. When you map to a attribute that requires conversion, the conversion
will display above the arrow when it is selected. Attributes that display red circles have incompatible data
types and you cannot map to them. See Supported data types and conversions on page 283 for a complete
list of supported data types and conversions.
6. When you have finished mapping, click OK to exit the mapping tool or click Response to map the response.
If you exit the visual mapper, you will need to open it again to map the response.
290 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Automating business decisions with Corticon rules
Response mapping
The following procedure assumes that you have already mapped the request and that the mapping tool is still
open. If the mapping tool is not open, click Configure in the Corticon Configuration area on the new or edit
screen of the trigger. If you have already selected a decision service for the trigger, the Input/Output mappings
screen opens and displays Rollbase objects and fields on the left and Corticon entities and fields on the right.
By default, the Request tab is selected; click the Response tab. If you have not selected a decision service,
select a service as described in Request mapping.
Note: You must configure access to one or more Corticon Servers before performing this step. See Configuring
Rollbase to access Corticon Server on page 287 for details.
To map the Decision Service response:
1. In the mapping tool, select the Response tab.
The Response tab is selected, allowing you to map fields for the response.
2. Optionally filter the list of Corticon entities by clicking the filter icon next to Corticon Object and selecting
the entities required for the mapping.
3. To map an attribute or message, select a circle next to a Corticon field and drag the arrow that appears to
a circle next to a Rollbase field. Note that you can only map to fields, not to entities.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 291
Chapter 6: Adding business logic
As you drag the arrow, the circles next to the Rollbase fields change color, indicating the fields whose data
types are compatible with the Corticon field. Fields that do not require conversion display green circles and
fields that require conversion display orange circles as shown below. When you map to a field that requires
conversion, the conversion will display above the arrow when it is selected. Fields that display red circles
have incompatible data types and you cannot map to them. See Supported data types and conversions on
page 283 for a complete list of supported data types and conversions.
4. When you have finished mapping attributes, click OK to exit the mapping tool or click Request to map the
request.
Overriding functions to provide custom behavior
Code for the formula that Rollbase generates is divided into two sections as shown in the screen below.
292 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Automating business decisions with Corticon rules
You should not change any code in the second section, labeled Generated code for Corticon Service trigger.
If you change request and/or response mappings, Rollbase regenerates this section of code.
The code in the first section contains function definitions that you can edit to customize processing and formatting.
Rollbase does not regenerate this code when you change mappings.
The functions you can edit and what each can customize include:
• processCorticonRequest() — Edit this function to add post processing to the request before sending
it to the Decision Service.
• processCorticonResponse() — Edit this function to add post processing to the response before writing
data to Rollbase records.
• formatDate() — Converts Date fields from Rollbase to a standard format accepted by the Decision
Service. Edit this function to change the format. The format needs to be supported by Corticon.
• formatDateTime() — Converts DateTime fields from Rollbase to a standard format accepted by the
Decision Service. Edit this function to change the format. The format needs to be supported by Corticon.
• formatPickListValue() — Converts Picklist values from the Decision Service's response. Edit this
function to customize the conversion.
• convertRequestData() — Converts request data by type; calls formatDate() and
formatDateTime(). Edit this function to add conversions for different data types.
• convertResponseData() — Converts response data by type; calls formatPickListValue(). Edit
this function to add conversions for different data types. See Supported data types and conversions on
page 283 for information about supported data type formats and an example.
• compareCorticonObject() — Compares the response to map a related Rollbase object. By default,
Rollbase passes the related object's ID when sending a request to the data service. The data service returns
the same ID when sending the response. Rollbase uses the ID to compare the related object and update
its value. Edit this function to add more conditions in addition to the default behavior.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 293
Chapter 6: Adding business logic
Example customization
The example below shows how to override the processCorticonRequest() and
processCorticonResponse() functions to saves the request, the response, the duration, and the timestamp
in fields in an Order record:
function processCorticonRequest ( requestData ) {
/* Add post processing to the Corticon request before making REST call -
by default we leave it untouched. */
rbv_api.setFieldValue('Order', '{!id}', 'decisionServiceRequest',
rbv_api.jsonToString(requestData));
return requestData;
}
function processCorticonResponse ( corticonResponseString, corticonResponseObject,
requestDuration, requestDateTime ) {
/* Add post processing to the Corticon response before writing fields and objects in
Rollbase -
by default we leave it untouched. */
rbv_api.setFieldValue('Order', '{!id}', 'decisionServiceResponse',
corticonResponseString);
rbv_api.setFieldValue('Order', '{!id}', 'decisionServiceDuration', requestDuration);
rbv_api.setFieldValue('Order', '{!id}', 'decisionServiceTimestamp', requestDateTime);
return corticonResponseObject;
}
The View page for Order includes a page tab that displays this information:
Example trigger mapping to related objects
This example calls a Corticon Decision Service that returns an estimated car insurance premium. It illustrates
how you can map fields from related objects in the request. The request mapping maps fields from two related
objects, Car and Person, where Car is the base object. The response mapping maps a field from the base
entity Request to a field in the Car object.
Request mapping
The request mapping maps fields such as Make, Model, and Gender from the Car and Person objects.
294 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Automating business decisions with Corticon rules
Response mapping
The response mapping maps the result of the calculation to estimate the premium to the Insurance Premium
field in the Rollbase object. Note that the Request entity node on the Corticon side is just a user-specified label.
Result
The example trigger is configured to run after create or update. The following screen shows the the values for
a new record:
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 295
Chapter 6: Adding business logic
After the record was saved, the following screen shows that the trigger received a response from the decision
service with the value of the insurance premium:
Example trigger mapping where response creates a record
This example calls a Corticon Decision Service that returns a risk assessment based on an applicant's age
and whether the applicant is a skydiver. It illustrates how the response mapping can create records. The
response includes a message, which is mapped to a field in a Message object. The trigger creates a Message
record each time it is called.
Request mapping
The request mapping maps the Applicant's Age and Skydiver fields to the decision service.
296 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Automating business decisions with Corticon rules
Response mapping
The response mapping updates the applicant's Risk Rating field and creates a related Message record with
the reason for the risk rating.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 297
Chapter 6: Adding business logic
Result
The trigger is configured to run after create or update. The following screen shows the values input into a new
Applicant record:
The trigger ran when the record was saved. The screen below shows the results. A new related Message is
now associated with the Applicant record indicating why the Risk Rating is High:
298 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Reports, charts, and gauges
Reports, charts, and gauges
To provide data visualization for end-users, Rollbase offers the following features:
• Reports that you can create and configure in the following ways:
• Tabular: Each row represents a data record and each column represents a field. Tabular reports can
include up to three layers to show dependent records.
• Document template: You can build custom Microsoft Word, Microsoft Excel, plain text, and XML document
templates that are used to display record data in pre-specified locations.
• HTML: You can create custom HTML documents that are used to display record data in pre-specified
locations.
• JavaScript: You can write custom JavaScript code to loop over a list of records, perform calculations
and analysis, and display results in custom HTML.
• Charts that present summaries of data in visual formats, such as bar charts, column charts, pie charts,
donut charts, line graphs, and others. Charts can periodically and automatically refresh themselves without
a complete page refresh. Some charts provide drill-down capabilities and interactivity options such as
rotation and slice movement.
• Gauges that present a single formula-based value in a way similar to a car's speedometer or a scale display.
Rollbase supports several different gauge types for various visual effects. Gauges can periodically and
automatically refresh themselves without a complete page refresh.
Working with reports
You can enable and disable reports per object in the object definition. The Reports Enabled checkbox is
available under Object Properties and is checked by default. To change the value, click Edit.
If you are using any right to left (RTL) languages in your report, you can specify that content is rendered RTL.
See RTL support in templates and reportsRight to left support in reports on page 342 for details.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 299
Chapter 6: Adding business logic
Creating Tabular Reports
Tabular reports are the most common type of reports in applications. Rollbase renders tabular reports as
rectangular tables in which each row represents a data record and each column represents a field value. You
can define up to seven layers in tabular reports with a list of related records rendered under the parent row.
Rollbase Private Cloud administrators can set the shared property TabularReportLayeringLimit to
override the default value; see Shared Properties on page 786 for more information.
You can create a new report in the following ways:
• Click New Report in the Reports tab in the default Rollbase application.
• Open an object definition, click Reports in the ribbon, and click New Report.
• Open any page containing a section with a report link and click New Report in that section's header.
Note that only administrators can create reports. For more details about user roles, see Role-based access
control on page 648.
300 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Reports, charts, and gauges
To create a tabular report:
1. Navigate to the New Report page using one of the methods described above.
2. Select an object type to report on and select Tabular as the Report Type.
3. Specify a Report Name.
4. Type a Description for the report.
5. In the Private category, select Private Reports are only available to their creator and Hide count of
total records for this View checkboxes as needed.
6. From the Export Options drop-down, select any one of the following options:
Traditional: Renders report columns with associated data across multiple rows.
Export Multi-levels as Flat List : Flattens" the exported data of the multi-layer tabular report.
Export multi-levels as flat list with no duplicates: To ensure that the data for each layer of the tabular
report is repeated in each row recursively with an option to flatten without repeating the data.
On the first row, add the object names of the object at each level and align the object name with the first
field exported with that level.
The data export layers limit is controlled by the shared property TabularReportLayeringLimit and is
applicable for export to XLS, XLSX and CSV formats.
Each level is limited to the maximum number of records as specified by the shared property MaxExportRows.
Here's a sample view of a multi-level flat list:
Here's a sample view of a multi-level flat list without repeats/duplicate records:
The following image shows an example of a report with three layers of data. Each layer can be expanded
or collapsed entirely by clicking either Expand All or Collapse All as well as individually by expanding or
collapsing each row:
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 301
Chapter 6: Adding business logic
7. In the Report Name Template field, specify a name for the report template. You can use date, month,
and/or year tokens. If you do not input any value, the name of the report is used as the file name by default.
Special characters are converted to underscore in file names.
Note: You can see the tabular report names reflected when you send report emails, create new batch jobs,
use report filters, and use report tokens in Document template.
302 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Reports, charts, and gauges
8. Specify the report columns, sorting and grouping, and report filters. You can report on all deployed objects,
system objects, audit trails, system error logs, and log-in history records.
If you want multi-layer reporting, that is, if each row in the report must include a report about the related
records, specify the Relationship between the two layers. You must define your report's columns, sorting
and filtering conditions for Layer 1, similar to the way you define list views but with the added option to select
a relationship for Layer 2 records. If you choose a related object to display in a second layer, Rollbase will
create Layer 1 and then open the Layer 2 edit page. You can create more layers in a similar manner if
desired. In the second and subsequent layers, you can report on comments and activity trail records related
to the Layer 1 record (that is, the parent record).
Note: You can make a report private if you want the report to be available only to you. Also, if your object
has defined charts, you can select a chart to be included in the report.
9. Click Save. The saved report appears in the Reports grid table.
Creating document template reports
You can create reports based on a document template. Document template reports are similar to document
templates, except that reports are designed to present information on multiple records rather than a single
record.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 303
Chapter 6: Adding business logic
To create a document template report, do the following:
1. Create a new report by doing any of the following:
• Click New Report in the Reports tab in the default Rollbase application.
• Open an object definition, click Reports in the ribbon and click New Report.
• Open any page containing a section with a report link and click New Report in that section's header.
2. Select an object to Report On and then select Document Template as your Report Type.
3. Specify a Report Name and provide description if required.
4. In the Report Name Template field, specify a name for a report template. As reports are not record specific,
you can use date, month, and/or year tokens. If you do not input any value, the name of the report is used
as the file name by default. Special characters are converted to underscore in file names.
Note: You can see the document template report names reflected when you preview/run the report, send
report emails, create new batch jobs, use report filters, and use report tokens in Document template.
5. Define your report template using the template helper (see Document templates on page 201).
6. Select one of the supported report file formats:
• Microsoft Word (Only DOCX)
• Microsoft Excel (XLS and XLSX)
• HTML
• CSV
• XML
• Plain text (TXT)
7. Optionally specify report filters for the object. For example, if you are generating a report on an object that
stores your customer information, then you can apply a filter that direct Rollbase to include only customers
from Asia in the report.
8. Specify the access permissions (see Access control on page 647).
9. Click Save.
Note: You can use an EVAL block to execute server-side JavaScript in document template reports.
Creating HTML template reports
HTML template reports are similar to document template reports. You don't have to upload a file, but can define
your HTML code within the report definition page.
304 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Reports, charts, and gauges
To create an HTML template report, do the following:
1. Create a new report by doing any of the following:
• Click New Report in the Reports tab in the default Rollbase application.
• Open an object definition, select Reports from the ribbon, and click New Report.
• Open any page containing a section with a report link and click New Report in that section's header.
2. Select an object to Report On and the select HTML Template as the Report Type.
3. Specify a Report Name and provide description if required.
4. In the Report Name Template field, specify a name for the report template. You can use date, month,
and/or year tokens. If you do not input any value, the name of the report is used as the file name by default.
Special characters are converted to underscore in file names.
Note: You can see the HTML report names reflected when you send report emails, create new batch jobs,
use report filters, and use report tokens in Document template.
5. Define your report template using the template helper. The following example shows a report definition that
prints a list of Lead records:
<html>
<head>
<h2>List of Leads </h2>
</head>
<body>
<table>
{!#LOOP_BEGIN.all#154785}
<tr>
<td>{!name#text}</td><td>{!type#value}</td>
</tr>
{!#LOOP_END.all}
</table>
</body>
</html>
Note that this report runs a loop through all records using a view with the original ID 154785. Inside the
loop, each record outputs a row of an HTML table.
For a summary report, you can use the Rollbase query API in an EVAL block.
6. Optionally, specify report filters for the object. For example, if you are generating a report on an object that
stores your customer information, then you can apply a filter that direct Rollbase to include only customers
from Asia in the report.
7. Specify the access permissions (see Access control on page 647).
8. Click Save.
PDF report options for HTML Template reports
While creating or editing an HTML Template report, you can render an HTML report as a PDF document.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 305
Chapter 6: Adding business logic
To render an HTML report as a PDF report:
1. On an Object definition page, click Reports in the ribbon and create or edit an HTML Template report.
The New Report or Edit Report page opens.
2. Click the Render as PDF check box. The PDF Options sub-menu appears with the following options:
• Header and Alignment — Specifies the PDF header and its alignment.
• Footer and Alignment — Specifies the PDF footer and its alignment.
Note: If you are a Private Cloud customer, PDF headers and footers are only available for PD4ML
Professional edition. As a prerequisite, you must configure PD4ML. See Configuring PD4ML on page
776 for more information.
• Page Size — Specifies the size of the PDF page. The default page size is Letter. Options include all
PD4ML-supported sizes as well as custom sizing.
• Landscape orientation — When selected, specifies that your PDF report be generated in landscape
orientation. Clear the check box to print in portrait orientation.
• Margins (mm) — Specifies the space (in mm) to be left for page margins. The default margin size is 20
mm.
• Smart table break — When selected, the header row of tables that span pages will be reproduced on
each page.
• Enable hyperlinks — When selected, hyperlinks are enabled in the PDF document.
• Render each record in new page — When selected, specifies that during PDF generation, each record
be rendered in a new page of the PDF. By default, during PDF generation, all the records in the HTML
template are rendered without any page breaks. Select this option only when you want to introduce page
breaks between each record in the rendered PDF.
Generated PDF documents have the following attributes:
• Author — Your customer name
• Title —The name of the report
In the PDF header and footer templates, you can use the following special tokens:
• ${page} — The number of the current page (starting from 1)
• ${total} — The total number of pages in the document
• ${title} — The document's title
In the body of the HTML to be rendered as PDF, you can use the following PDF-specific tags:
• <pd4ml:page.break> — Separates sections of the HTML report rendered as PDF
• <pd4ml:attachment description="..." src="http://..." icon="Graph - PushPin -
Paperclip - Tag" /> — Includes content of the specified URL as an attachment to the PDF.
Creating JavaScript reports
JavaScript reports allow you to loop through a list of records and use server-side JavaScript (or formulas) to
generate output. You can also invoke complex logic and run queries using the Rollbase query API.
306 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Reports, charts, and gauges
To create a JavaScript based report, do the following:
1. Create a new report by doing any of the following:
• Click New Report in the Reports tab in the default Rollbase application.
• Open an object definition, select Reports from the ribbon, and click New Report.
• Open any page containing a section with a report link and click New Report in that section's header.
2. Select an object to Report On and the select JavaScript as your Report Type.
3. Specify a Report Name and provide description if required.
4. In the Report Name Template field, specify a name for the report template. You can use date, month,
and/or year tokens. If you do not input any value, the name of the report is used as the file name by default.
Special characters are converted to underscore in file names.
Note: You can see the JavaScript report names reflected when you send report emails, create new batch
jobs, use report filters, and use report tokens in Document template
5. Define a JavaScript report:
• Select the Content Type of the output: Plain Text, HTML, XML Document, or CSV Spreadsheet.
• Optionally define JavaScript to generate the report header.
• Select a view to use to loop through the selected object's records.
• Define JavaScript to be executed for each record in the loop.
• Optionally define JavaScript to generate the report footer.
Inside the header, body and footer you can use the rbv_api.print() on page 1019 or rbv_api.println() on page
1020 methods to generate the report's output.
The following example reports a list of Lead records:
Header:
rbv_api.println("Hot Leads\n=========================");
Body:
if ("{!lead_type#code}"=="HOT")
rbv_api.println("{!name#text}");
This will generate a text report that looks like:
Hot Leads
=========================
Per Hanseon
jose del pino
sawyer joe
Todd Geist
Bob Myers
If you are using complex business logic to process a report's records, consider running the report
asynchronously using a batch job.
6. Optionally specify report filters for the object. For example, if you are generating a report on an object that
stores your customer information, then you can apply a filter that direct Rollbase to include only customers
from Asia in the report.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 307
Chapter 6: Adding business logic
7. Specify the access permissions (see Access control on page 647).
8. Click Save.
About Custom Reports
A custom report is a specialized, business-specific report that you create to meet the exact needs of your
organization. Rollbase enables you to create custom reports using the Report Builder capability and customize
the report templates based on a combination of criteria.
Key Features
• Create a custom report across multiple related objects
• WYSIWYG Report builder for designing custom report
• Flexible options to add a variety of sections to your report
• Automate reusable sections/sub-sections of a custom report using the Loop feature
• Multiple formatting options for the report content - both pre-defined and custom
• Choose to export the custom report output as a HTML or PDF
Types of Custom Reports
You can create the following types of custom reports based on your business need:
• Record Specific Custom Report: A record specific custom report is designed to execute against a specfic
or selected record for a defined object.
• All Records Custom Report: This type of custom report is designed to execute against all records of a
defined object.
Note: You will be able to view custom reports created prior to the Rollbase 5.1
Limitations
• Previously created custom reports can be edited and saved as a new enhanced custom report. However,
the application cannot be imported into a Rollbase version less than 5.1
• As a best practice:
• Recreate filters with date intervals to enhance the existing custom reports.
• Recreate the loops as the design of the reports have been enhanced.
• Filters cannot be applied on doc template, email template, formula, integration link, and password fields.
• An HTML output can use all HTML and CSS constructs that browsers support, but a PDF output is limited
to PD4ML capabilities. Refer this specification http://pd4ml.com/css.htm to learn more.
Custom Reports: Example
Consider a CRM application with the following two types of customized "customer" reports:
308 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Reports, charts, and gauges
• A custom report that opens "Current cases for each customer" is an example of a Record specific
custom report at customer record level.
• A custom report that groups "All Leads records by status" is an example of All records custom
reports.
Selecting a Custom Report Type
The very first step to creating a custom report involves selecting a custom report type - Record Specific
Custom Report or All Records Custom Report. This topic describes the procedure to select a custom report
type.
Prerequisite: Ensure that you have created object(s) and an application.
Perform the following steps to select a custom report type:
1. Navigate to Setup Home > Applications Setup > Objects and select an existing object. The object definition
page appears.
Note: The selected object becomes the base object on which you will build the custom report.
2. Select the Reports tab in the objection definition page. This will bring focus to the Reports grid.
3. Click New Report. The New Report page appears displaying a list of report types for selection.
Note: You can opt to change the base object for your custom report by selecting from the Object Type
field.
4. Select the required custom report type: Record Specific Custom Report and All Records Custom Reports.
5. Click Next. The Report Builder page appears displaying the following information:
• The auto-generated name of the report
• Report Header and Report Footer properties. See Working with the Report Builder on page 310 for more
information
• Report Properties. See Working with the Report Builder on page 310 for more information.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 309
Chapter 6: Adding business logic
Note:
You can clone an existing custom report by clicking the Clone button associated with a custom report in the
Reports grid of the selected Object Definition page. the advantage of a cloned custom report involves replicating
and retaining similar report sections without the effort of re-creation.
While cloning a custom report, you will be prompted to confirm the cloning action. Upon confirming, the cloned
report automatically opens in edit mode for you to work on it.
Next Task: Working with the Report Builder
Working with the Report Builder
As the name indicates, the Report Builder is a WYSIWIG editor that you use to design the custom reports.
Use the Report Builder to create and organize your custom report sections, to edit the header and footer
information that will appear on each page of the report, and to save and preview the report. A custom report
can contain multiple sections and sub-sections, a table of content, headers and footers. You can configure the
sections to generate content from object records.
Here's a sample view of the Report Builder.
Interface
The Report Builder editor comprises capabilities that are described in the table below, using which, you can
perform specific actions while creating a custom report.
310 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Reports, charts, and gauges
Report This is the auto-generated name of the custom report. By default, the report name is a combination
Name of the date/time stamp of the report created. Click the associated edit icon to edit the default
name and to reflect a suitable name. You can also edit the report name from the General tab of
the Report Properties.
When saved by clicking the associated Tick icon , the report name appears on the top of your
custom report.
Report This appears as a gear or settings icon on top of the report builder. Click this icon to view the
Properties Report Properties comprising the following tab views:
• General: In this view, you can perform primary actions such as editing the Report Name,
choosing a format for the Report Name Template, adding a Description for the report. For
the report name template, you may use the date, month, and/or year tokens and special
characters are converted to underscores in file names. Select the Private Report option if
you want to flag your report as private. Private reports are available only to the report creator.
Select the Render as PDF option and configure the page specifications to render a PDF
version of the report output. The Context Record Specific label is a read-only only flag that
appears only if the report is context specific.
• Styling: This view displays the default CSS for the custom report. Start typing your custom
CSS in the blank text area. Alternatively, choose to select the Add Hosted CSS File option
to select your custom CSS file.
See Hosted files and Custom CSS for more information.
Note:
When selecting a report to render as PDF, apply the CSS rules that support PD4ML. Refer
http://pd4ml.com/css.htm to know more.
• Permissions: This view displays the available list of user roles and individual users associated
with the application. As an administrator, provide view report permissions to required user
role(s) or select a specific user(s) to view the report. See Access control on page 647 for more
information about setting permissions.
Click OK to save and exit from the specified report properties.
Report The Report Header appears as a horizontal bar with an accordian-like collapse/expand
Header functionality and contains the Header Properties. This is a mandatory and pre-defined section
type with fixed position and cannot be removed.
Configure required header information which you would like to see in the report header using
the rich HTML editor and the Token Helper from the Header Properties. When the render as
PDF option is selected, custom report tokens let you add page numbers, values from records,
and other text to headers and footers. Tokens are resolved when the report is generated. For
more details on tokens, see Using Tokens in Custom Reports.
For example, if you want the report's Header to contain the name of the report, you can insert
the Page Title token. If the render as PDF option is not selected, you will be able to view only
the Current User and Current Customer tokens.
Note: The report header and footer content is repeated in every page if you render a report as
PDF. When a custom report is rendered as HTML, the Header information appears at the top of
the report.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 311
Chapter 6: Adding business logic
Report The Report Footer appears as a horizontal bar with an accordian-like collapse/expand
Footer functionality and contains the Footer Properties. This is a mandatory and pre-defined section
type with fixed position and cannot be removed.
Configure required header information which you would like to see in the report footer using the
rich HTML editor and the Token Helper from the Footer Properties. When the render as PDF
option is selected, custom report tokens let you add page numbers, values from records, and
other text to headers and footers. Tokens are resolved when the report is generated. For more
details, see Using Tokens in Custom Reports.
Note: The report header and footer content is repeated in every page when the report is rendered
as a PDF output. When a custom report is rendered as HTML, the Footer information appears
at the bottom of the report.
Add New This appears as a Plus icon in the Report Builder. Click this icon to add a new report section(s)
Section to your report. Note that each newly added section appears within the Report Header and Report
Footer bars.
Sections form the crux of the custom reports functionality because the real capability to customize
your report design lies within the configuration of sections and sub-sections. There is no limit on
adding sections and sub sections to a custom report. For information on how to configure multiple
sections of various types to the report, see Section Types and Section Properties.
Action Buttons
Actions buttons in the Report Builder editor enable you to perform the following actions:
312 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Reports, charts, and gauges
• At the report level: Report level action buttons provide access to Report Properties and Help &
Documentation.
• At the report Header/Footer level: The action button provides access to the report header/footer properties
and the rich HTML editor.
• Access section properties: Click the left arrow button to quickly access the Section Properties if you
have hidden it earlier from the view in the right pane of the Report Builder and click the right arrow
button (if expanded) to collapse the section properties view.
• At the section/sub-section level: The action buttons allow you to perform specific actions such as:
• Create a new report section: When you click this icon which is represented as a Plus sign, you will be
prompted to choose from Add Section Above, Add Section Below and Add Subsection. Select the
required positioning of the section. Selectiong Add Subsection creates a new section as a subsection
within the section in context. There is no limit to the number and types of sections that you might want
to add within or beyond a section.
• Create a copy of this section: Creates a new section that a copy of the current section.
• Delete this section: Deletes the selected section from the custom report.
• Full Screen and Restore Down options for every section.
• Report Actions: As the name indicates, you can perform these actions on top of a custom report.
• Save and Preview: Saves the custom report and generates a Preview in the new tab of your browser.
Note: Ensure that the pop-up blocker of your browser is disabled for the custom report Preview to
appear.
• Save: Saves changes to the custom report allowing you to continue with designing the report further.
Note: Alternatively, you can save your changes by using a keyboard shortcut that uses the accesskey
attribute on the save button (accesskey="S"). For example, if you use Chrome browser, you must use
the keyboard shortcut ALT+S to save. Refer
https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/accesskey to know about other
browser keyboard shortcuts. In custom reports, this is the only action that has an access key attribute.
• Close: Cancels an action if the custom report is not saves. Exits view from the Report Builder and
navigates the view to the object definiton view of your base object.
Next Task: Designing a Custom Report
PDF Report Options for Custom Reports
When creating or editing a custom report, you can specify if a report must be rendered as a PDF document.
Only reports rendered as PDF documents can contain a table of contents. See Section Types on page 319 for
details.
To configure PDF properties for a custom report:
1. From the Reports section of an object definition page, do one of the following:
• Create a new report (see Selecting a Custom Report Type on page 309), select a custom report type,
and click Next.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 313
Chapter 6: Adding business logic
• Open an existing custom report.
In the Report Properties window:
2. Click the Render as PDF check box. The PDF Options section appears with the following options:
• Page Size — Specifies the size of a PDF page. The default page size is Letter. Options include all
PD4ML-supported sizes as well as custom sizing.
• Page WIdth(in inches) — Specifies the width of a page when custom page sizing is selected.
• Page Height(in inches) — Specifies the height of a page when custom page sizing is selected.
• Page Orientation — Specifies the orientation of a PDF page (Portrait and Landscape). Portrait is the
default value.
• Page Margins (mm) — Specifies the Top, Right, Bottom, and Left margins in mm.
• Page Numbers — When turned on, page number format, positioning (to be displayed in header or
footer), and alignment can be specified.
Note: You can choose to custom format page number using tokens from the header/footer section
properties. However, you must ensure that the Page Numbers report property is turned off to avoid
page number duplication.
• Pages to skip (Header) — Allows a certain number of initial pages to not have a header. This is useful
when you do not want a header on cover pages, prefaces, etc. Note that you need to tune this property
based on the content generated and is useful only if you know how many pages these initial sections
are going to occupy.
• Pages to skip (Footer) — Allows a certain number of initial pages to not have a footer. This is useful
when you do not want a footer on cover pages, prefaces, etc. Note that you need to tune this property
based on the content generated and is useful only if you know how many pages these initial sections
are going to occupy.
• Smart table break — When selected, it switches on/off the table break feature. If set to true, it inserts
page breaks in between table rows to fit the table as per the PDF page height. If the table has a header,
the header row that span pages will be reproduced on each page.
Note: This does not support nested tables and multi-page rowspans.
• Enable hyperlinks — When selected, hyperlinks are enabled in the PDF document.
When you run the report, it will be rendered as a PDF document with the specified properties.
Designing a Custom Report
Designing a custom report is central to the custom reports capabilities. In that, it involves tasks such as adding
multiple sections and sub-sections of various types depending on your business need and performing specific
actions using the action buttons. Report creation happens within a single object - also, known as the base
object. So, ensure that all other objects in the app are related to the base object.
Perform the following steps to design a custom report:
314 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Reports, charts, and gauges
1. Click the edit icon on top of the Report Builder to edit the Report Name.
2. Configure the Report Properties.
3. Configure the Report Header.
4. Configure the Report Footer.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 315
Chapter 6: Adding business logic
5. Click the Add New Section icon. The Add New Section dialog appears.
316 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Reports, charts, and gauges
6. Select a Section Type from the drop down. For example, select the Tabular section type, and click OK.The
selected section type appears between the Report Header and Report Footer. Section Properties appears
in the right pane of the Report Builder.
The section properties accordion can be expanded on click of left arrow button and collapsed on click of
right arrow button (once expanded) in the right pane of the Report Builder.
Depending on the selected section type (for e.g. Tabular), the section components such as Select Fields,
Define Criteria, Apply Filter and No Records Message appear.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 317
Chapter 6: Adding business logic
Note: Refer Section Types for more information on the usage of each section type.
7. Click the Create a new report section that appears as a Plus icon on top of the section header to Add
Section Above, Add Section Below and Add Subsection.
8. Configure the section components. Refer Section Types for more information.
9. Save the custom report.
Section Properties
In custom reports, every section contains editable section properties. The section properties pane comprises
two tab views: General and Token Helper.
You can set the following properties for a section:
• Section Type: A specific section that is unique with its specific behavior, which makes it easy to distinguish
from any other section. See Section types for the available section types.
• Source Object: An object based on which the section generates report information. This can be the same
object as the report is based on or another object in the application. The selected section object need not
have a direct relationship with the report object.
• Section Identifier: A code name for easy identification of the section and is not reflected in the final report.
This remains in the back-end for developer use.
• Section Title: A title that appears as a section header or name in the final report. You can use tokens in
this field (indicated by the lightening bolt icon). Rollbase resolves the tokens when generating the report,
which, for example, allows the section to have a title that is specific to a particular record.
• Use identifier as title: When selected, the section identifier is rendered as the section title.
• Scope of the Loop: Consider choosing a relationship of the Source Object as the scope. The scope indicates
all the records that the loop will iterate through.
• Start on a new page: When selected, the section will appear on a new page in the custom report.
318 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Reports, charts, and gauges
• Show in Table of Contents: When selected, the Section Title appears in the TOC of the final report.
• Print Title: When selected, the Section Title is printed as as the section name/title in the final report.
• Section Title for loop record: This option is applicable only when Print Title is checked for a non-loop
sub-section. When selected, you can choose to, Show once (section title will be printed only once for a
loop iteration) or Show for each loop record (section title will be printed for each loop record iteration).
• Section Comments (optional): Type a description for reference purpose, if needed. This has no effect
on the generated report.
Note: When designing a custom report, at any time, click the Access this section section properties icon
on the section header to open theToken Helper to use an available token from the available list of tokens. See
Using tokens in custom reports on page 337 for more information.
Section Types
Plain Text & HTML
When you select Plain Text & HTML as the section type, a rich HTML editor where you can enter the content
of the section is added. You can also style and format the section using the toolbar available in the editor.
You can use tokens in the section properties; tokens are resolved when the report is generated. For more
information about tokens, see Using tokens in custom reports on page 337
Tabular
When you select Tabular as the section type, it lets you select fields and configure sorting, grouping, and
TotalBy. Also, you can apply filter for the tabular section to control what you see in the final report.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 319
Chapter 6: Adding business logic
Tabular section will loop through records from the source object and output the selected fields in a table format.
You must select at least one field in tabular section to save the report. Tabular section consists of four tabs:
Select Fields, Define Criteria, Apply Filter, and No Records Message.
Select Fields
Using the Select Fields tab, you can drag fields from Available list of fields to Selected fields list. Also, you
can rename a selected field label by clicking on edit (pencil) icon and reorder the column by dragging it to a
desired position. To remove selected field from the list, either click on Delete or drag it back to available list of
fields. To search for available fields, you can use the Search field in the top.
Define Criteria
Using the Define Criteria tab, you can Group By, Sort By, and Total By the fields you selected.
• Group By is a drop-down menu which lists fields that you can use for the grouping operation. Next to the
drop-down, there is an icon to select the direction of the group by operation. The two supported directions
are ascending and descending. The default direction is ascending.
• Sort By is a drop-down menu which lists the selected fields that you can use for the sorting operation. You
can select upto three fields. Next to the drop-down, there is an icon to select the direction of the sort by
operation. The two supported directions are ascending and descending. The default direction is ascending.
• Total By is a drop-down menu which lists the selected fields that you can use for the total by operation.
You can select upto three fields.The field next to the drop-down list is auto-populated with an appropriate
total function based on the field selection made.
Note: Grand total cannot include formula fields. The allowed number of Total By fields is controlled by
MaxListTotals shared property. See Shared Properties on page 786 for more information.
Apply Filter
The Apply Filter tab enables you to filter records that are rendered as a part of a section. See Applying Filters
to a Custom Report on page 335 for more information.
No Records Message
320 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Reports, charts, and gauges
You can add a message to be printed in a table when there are no records available. The default message is,
There are no records.
HTML Template
When you select HTML Template as the section type, an HTML Template section that includes two tabs,
Define Template and Apply Filter is added.
The Define Template tab contains a code editor and a template helper. The Template helper provides tokens
and API helper that enables you to define your own HTML template.
The Apply Filter tab enables you to filter records that are rendered as a part of this section. See Filter criteria
on page 443 for more information.
Loop
The enhanced custom report editor offers greater flexibility and control to create all sorts of content using loop
sections. In a loop section, you can choose the fields and render the output in different formats for report
generation in a loop section. For example, you can drag & drop fields and have Table, Bullet List, Number List
& Custom formatted render patterns where a loop starts on the selected source object records taking into
account the sorting and filter criteria applied. For each record, sub-sections of this loop will also be executed.
Loop section content can be constructed using templates or by adding sub-sections. You can use Loop tokens,
Current User and Current Customer tokens in the template to construct the content. For each loop section,
you can control the HTML that will be generated. We recommend you to use tokens that are not of formula
fields to avoid undesired behavior in the loops. For more information about tokens, see Using tokens in custom
reports on page 337.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 321
Chapter 6: Adding business logic
Wizard View in Render Patterns of Loop Section
On adding a new loop section, a wizard view is displayed for the Table, Bullet list or Number list render
patterns. The fields can be dragged & dropped from available field container under the Define Template tab.
The parent object fields can also be dragged & dropped by selecting the relationship for the Source Object
from the drop-down.
Render Pattern Properties
The Table, Bullet list or Number List render pattern properties can be configured using the settings icon
beside the Render Pattern drop-down.
322 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Reports, charts, and gauges
In the Table type of render pattern, the following parameters can be configured:
• Table Width - The table width can be either percentage (%) or pixel (px). By default, the value for the table
width is set to 100%.
• Alignment – The table can be aligned to left, center or right. By default, the alignment is set to Left.
• Indentation – The indentation of table from left in pixels (px). It works according to the table width and is
enabled only when table alignment is left. By default, the value for indentation is set to auto.
• Row Height – The height of each row of the table in pixels (px). By default, the value for row height is set
to auto.
• Column Width – The width of each column of the table in pixels (px). By default, the value is set auto and
gets adjusted based on the number of columns in the table.
• Layout – The layout of the table can be set to either Flat or Hierarchical . By default, the layout is set to
Flat.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 323
Chapter 6: Adding business logic
In the Bullet list or Number list type of render pattern, the following parameters can be configured:
• List Formats – The list can be of any mentioned format. For Ex: disc, decimal, circle, number, alphabetical,
etc.
• Field Separator – A field separator for each listed item.
• Alignment – The list can be aligned to left, center or right. By default, the alignment is set to Left.
• Layout – The layout of the table can be set to either Flat or Hierarchical . By default, the layout is set to
Flat.
The Loop section has the following three tabs.
• Define Template — Defines template to construct content with the help of token helper. That is, you can
view a loop section as a way to define a container. There are three templates under the Custom type of
render pattern you can define:
• Loop Start — Executed before the iteration of records.
• Loop Content — Executed on each loop record. After the content template is executed for a record,
the sub-section of current section will be executed.
• Loop End — Executed after the iteration of records.
324 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Reports, charts, and gauges
Note:
• You can create nested containers in a loop section. See Examples: Loop section on page 327 for
more information.
• When loop templates are used, you must follow proper HTML standards to close all opened HTML
tags. If not, you might face an out of memory issue for a report that runs on large number of records.
• The Define Criteria tab enables you to sort and filter out records that are rendered as a part of this section.
See Applying Filters to a Custom Report on page 335 for more information.
• In the No Records Message tab, you can add message to be printed only in the Table type of render
pattern when there are no records available. The default message is, There are no records.
Below are the two modes explained for adding No Records Message for Table type of render pattern..
• Default mode – Based on Rich text editor. By default, this mode is set for adding No Records Message
in the Table type of render pattern. The generated report consists of a table with headers and the
message written in the editor and displays the message inside the table when no records are available
Note: No Records Message occupies the entire table width when no records are available.
• Custom mode – Based on HTML editor. The generated report gets executed from the html script written
in the editor and displays the message when no records are available.
• For other types (except table) of render patterns, the html editor enables you to add the customized message,
when there are no records available.
Note: No record message template is important for loop section to maintain the structure of HTML. Follow the
below samples to provide a no record template.
Example: No Record Message Custom Templates
Example 1: Table as template
Content Template
<tr><td> {!#LOOP_REC.name#text} </td>
<td> {!#LOOP_REC.city#value}</td>
<td> {!#LOOP_REC.country#value} </td>
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 325
Chapter 6: Adding business logic
No Records Message Template
<tr><td colspan ="3"> There are no records. </td></tr>
Example 2: Order or Unorder List as Template
Content Template
<li> {!#LOOP_REC.name#text} </li>
<li> {!#LOOP_REC.city#value} </li>
<li>{!#LOOP_REC.country#value}</li>
No Records Message Template
<li> There are no records. </li>
Example 3 : Any other template
Content Template
<div> {!#LOOP_REC.name#text} </div>
No Records Message Template - There are no records
Loop Tokens
Current User and Current Template tokens are available for all sections . Whereas, the Loop tokens are available
only for Loop sections and sub-sections of a Loop section.
There are some special cases where you want to access the parent Loop token from a sub-section. The
following table shows how to access the name field token from parent Loop A.
Table 2:
Section Type Sub-section Content Token Header Token
Loop A No {!#LOOP_REC.name#text} Loop token not applicable
Loop B ( Sub Section Yes {!#LOOP_REC.parent(0).name#text} {!#LOOP_REC.name#text}
under A)
Loop C ( Sub-Section Yes {!#LOOP_REC.parent(1).name#text} {!#LOOP_REC.parent(0).name#text}
under B)
Loop D ( Sub-section Yes {!#LOOP_REC.parent(2).name#text} {!#LOOP_REC.parent(1).name#text}
under C)
Plain HTML ( sub-section Yes {!#LOOP_REC.name#text} NA
under A)
Plain HTML (Sub-section Yes {!#LOOP_REC.parent(0).name#text} NA
under B)
Plain HTML (Sub-section Yes {!#LOOP_REC.parent(1).name#text} NA
under C)
Table of Contents
Custom reports do not have a table of contents unless you add a Table of Contents section. You can add this
section anywhere in the report.
When you select Table of Contents as the section type, Rollbase creates a placeholder section that is populated
when the report is generated. Table of content lists titles of all sections that has the Show in TOC property
selected.
Note: Rollbase generates a table of contents only for reports rendered as PDF documents.
326 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Reports, charts, and gauges
Sub-Report
When you select Sub-Report as the section type, a section in which you can select an existing non-custom
report is added. The content of the selected report will be the content of this section. Only reports defined for
the Source Object are available.
Note: If a multi-layer tabular report is embeded in the sub-report section, only the first layer is printed.
Examples: Loop section
In a loop section, you can choose the fields and render the output in different formats for report generation.
For example, you can drag & drop fields and generate the output in Table, Bullet List, Number List & Custom
formats.
You can also create nested containers in a loop section using the custom type render pattern. For example,
you can have nested tables or a table as the first level and a list as the second level.
Note: When you define a nested loop section, the ouput of the loop end for the parent level is generated after
the nested loop (child) output generation. That is, the rendering is done in a sequential order.
The following sections provide you examples of all the render patterns which can be used in a typical loop
section.
Table Render Pattern
In this example, an output with the list of fields related to Department as source object is generated. The render
pattern as Table can be selected from the drop-down available in the top right corner of the section body. To
customize the table properties, you can also click the gear icon beside the Render Pattern drop-down.
The following image shows the contents of the loop container.
The generated report for the Table type render pattern looks as follows:
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 327
Chapter 6: Adding business logic
Bullet List Render Pattern
In this example, an output with the list of fields related to Department as source object is generated. The render
pattern as Bullet List can be selected from the drop-down available in the top right corner of the section body.
To customize the bullet list properties, you can also click the gear icon beside the Render Pattern drop-down.
The following image shows the contents of the loop container.
The generated report for the Bullet List type render pattern looks as follows:
328 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Reports, charts, and gauges
Number List Render Pattern
In this example, an output with the list of fields related to Department as source object is generated. The render
pattern as Number List can be selected from the drop-down available in the top right corner of the section
body. To customize the number list properties, you can also click the gear icon beside the Render Pattern
drop-down.
The following image shows the contents of the loop container.
The generated report for the Number type render pattern looks as follows:
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 329
Chapter 6: Adding business logic
Custom Render Pattern - Simple list
In the following example, an output with a list of EAP Updates as an ordered list is generated. So, the container
is defined with a start tag <ol> and an end tag </ol>. Each record is output as a list item, <li>.
Note: If you want to sort and limit the records output, you can use the sort and filter features in the Define
Criteria tab.
Custom Render Pattern - Nested list
In this example, an output with the list of EAP updates and feedback of each updated EAP is generated. A
nested loop is used to achieve this. For this, a parent loop container is defined with a start tag <ol> and an
end tag </ol>. Each record is output as a list item, <li>. Then, a sub-section (child loop) is used to generate
the feedback for each EAP update.
Note: You must not close the <li> tag in the parent loop as the nested loop content needs to be appended
inside the list element. You must close the list element inside the nested loop (child loop).
The following image shows the contents of the parent loop container.
330 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Reports, charts, and gauges
The below image shows the contents of the child loop container that generates the feedback for every EAP
update.
Note: In the above image, notice how to close the parent list element in the Loop End template as well as add
a div to create spacing.
The generated report looks as follows:
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 331
Chapter 6: Adding business logic
Nested tables
In this example, an output with the list of EAP updates and feedback of each updated EAP is generated. A
nested loop is used to achieve this as the above example. The difference being, the generated report will be
in a HTML tabular format instead of a list.
The following image shows the contents of the parent loop container.
The below image shows the contents of the child loop container that generates the feedback for every EAP
update.
332 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Reports, charts, and gauges
Note: In the above image, notice how to close the parent <tr> element in the Loop End template.
The generated report looks as follows:
Loop to render images in same line
The below example shows how you can render images in same line using a div container and a span.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 333
Chapter 6: Adding business logic
A CSS class is used to address the images inside the container in a unique fashion (without affecting other
images in the report). This allows you to specify a width and some spacing between each image. It is defined
in the report properties as, .loopImgs img { width: 100px; padding: 5px; }.
The generated report looks as follows:
Loop to render images in a table
The following loop section example shows how to build a loop to generate a table with images.
334 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Reports, charts, and gauges
A unique id is specified for the table. This allows you to handle images inside the container in a unique fashion
(without affecting other images in the report). It is defined in the report properties as, #loopImgs img {
width: 500px;}.
The generated report looks as follows:
Applying Filters to a Custom Report
Filters support is added for custom reports with section types - HTML Template, Tabular, and Loop. The filter
mechanism is same as the existing view filters. See Filtering views on page 442 for more information.
As a part of custom reports enhancement, filters are now available in Basic Filtering Section and Advanced
Filtering Section.
Basic filtering section
When defining a view, you can add detailed filter criteria to narrow the result set. This filtering mechanism is
the same that Rollbase uses for object-specific searches and for reports to determine which records are shown
in the output.
The filter mechanism allows you to add filters by selecting a field, an operator, a value, and a date interval.
See Filter criteria on page 443 and Filtering by date intervals on page 443 for more information.
You can add more filters by clicking the + button. By default, you can add only five filters. You can change this
value by modifying the MaxFilters shared property. See Shared Properties on page 786 for more information.
Simillarly, you can remove filters using the - button. A valid filter entry will have field and operation auto-selected.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 335
Chapter 6: Adding business logic
The Condition Expression value is auto-generated from valid filter entries. A valid filter entry must have a
field and an operation selected.
You can modify the conditional expression value by selecting the Override Expression checkbox . If the
checkbox is selected, the expression value doesn't get auto-generated even on modification of filters. Also,
AND/OR toggle buttons are hidden.
Note: Each filter (except last one) will have AND or OR join type toggle buttons. So that you can specify join
type condition per filter.
The below example shows how to filter and fetch all records that are having name as "Progress Hyderabad",
created last week, or all records created by current user. You can modify conditional expression by adding
parenthesis to run them in different ways.
Advanced filtering section
While filtering views based on expressions offers a lot of flexibility, it does not cover all possible filtering scenarios.
For this reason, Rollbase offers filtering by a formula. To filter a view by a formula, click Switch to Advanced
Filtering.
336 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Reports, charts, and gauges
The page displays the Formula Helper, where you can define the formula.
You must use an Object's field integration name while using a filed in a formula. The Formula Helper area
can help you find the integration name. If you select the field from the Select Merge Token field, the subsequent
field displays its integration name. Copy this name and use it in the formula. The following simple example of
a filter formula, filters author names in a library application to only view titles with author name as Dan Brown:
A filter formula can include tokens derived from the current date as shown above. See Filtering by formula on
page 445 for more information..
Using tokens in custom reports
You can use report-specific tokens in section titles, section content, report headers, and report footers. Depending
on the context, different sets of tokens are available. You select tokens by accessing the Token Helper tab of
Section Properties in the upper-right corer of a section. This lists the available tokens. From here, you can
drag and drop the tokens into a section editor to use them. In sections that use template helpers, such as HTML
Template sections, and sections that use filter criteria, such as Loop sections, you can also use any available
Rollbase tokens.
The following table lists the report-specific tokens and where they are available:
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 337
Chapter 6: Adding business logic
Token Description Where available
Context Record The top-level record from which the report is generated Everywhere, for reports designed to
run on a single record.
Current User The currently logged-in Rollbase user Everywhere
Current The customer account for the currently logged-in user Everywhere
Customer
Loop Record The current record in an executing Loop section Sub-sections of Loop sections
Page Title The name of the report Headers and footers (for reports
where Render as PDF is selected)
Page Number The page number of the report Headers and footers (for reports
where Render as PDF is selected)
Count of total The number of pages in the report Headers and footers (for reports
pages where Render as PDF is selected)
Token Helper also supports search of tokens based on the text entered in the search text field.
The following screen shows the token generated for the Loop Record's Author field:
The following screen shows tokens used in a section header:
338 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Reports, charts, and gauges
The following screen shows the resulting header in a report preview:
Running and Accessing a Record Specific Custom Report
The Report Builder includes a Save & Preview button that opens the report in a preview window.
You can run a custom report designed to run on a single record by accessing the report from an application
page. Follow these steps to enable viewing a report that runs against a single record:
1. Create a document template for the object on which the report is defined.
2. Using the template helper for the document template, insert the custom report's body token into the template
body:
3. Create a document template field for the object.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 339
Chapter 6: Adding business logic
4. Select the document template you created.
5. Add the document template field to a list view.
You can now run the custom report from an application page that uses a list view by clicking the document
template field:
Running reports
After creating a report, you can use the page editor to add a Report Link Fields component to a section in
any generic page or records list page.
Users with View permission on a particular report can run the report by clicking the report's link. Users with
Manage Reports administrative permission can create, edit, delete, or set permissions for a report. For more
information about Rollbase permissions, see Access control on page 647.
Tabular reports are limited to regular pages, but links to template-based reports, including JavaScript reports,
can be used on portal pages.
Complex reports, especially template-based ones, might require a long time to execute. In such a scenario,
you can place the report in a queue for asynchronous execution by clicking Email this Report.
Click the new report button next to the section title to create a new report.
The screen below shows the menu options for a report:
When running a report, you can use dynamic report filters to filter Layer 1 records. Filtering reports works the
same way as dynamic filtering in list views.
340 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Reports, charts, and gauges
When you open the first report page, it renders the report with default filters specified when the report was
created, if any. You can dynamically update these filters and click Apply Filter to render the report again with
the new filter values. Click Clear Filters to restore the default (which might be empty) filters:
If you do not have a Dynamic Report Filters element in your report page, use the page editor to add it to the
page. See Editing pages on page 369 for information about the page editor.
In a report page, you can use the following operations:
• Run Report - Displays the report with the currently selected filters.
• Print - Displays the report in a pop-up window ready for printing. This option is only available for
template-based reports.
• Reset Filters - Resets the filters to the original report's selection; clear filters if no filters are selected in the
report.
• Edit this Report - Open the report for editing (if the current user has permission to manage reports).
• Expand All or Collapse All - To expand or collapse all the rows in the report.
• Export - You can export the report data to XLS, XLSX, CSV, or PDF format. When exporting multi-layered
reports, each record from each layer is exported as a unique row.
• Column data options for tabular reports:
• Sorting - Click a column header to sort its data in an ascending or descending order.
• Column selection - Click the down-arrow button on a column header to specify the columns to be made
available in the report.
• Column arrangement: Rearrange columns by dragging the column header to a different position in the
table.
Merging reports
You can create reports that encompass other HTML-based or JavaScript reports. Use {!#REPORT.123456}
tokens available in the template helper section to identify the reports you want to merge (note that these tokens
use the original IDs of the reports).
To specify the reports you want to merge in a new report:
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 341
Chapter 6: Adding business logic
1. Create a new HTML or JavaScript report.
2. In the Define Report Template section's Template Helper, select Reports from the drop-down list at the
left as shown in the example below.
3. From the drop-down list in the center, select the name of a report you want to merge. In the example below,
Report: Title Report 1 [body] is selected. The programmatic expression for the report is displayed in the
text box below the drop-down fields. Use this token in the HTML template where you want the report to
appear.
4. Similarly, select another report you want to merge from the center drop-down list and copy its programmatic
expression to the HTML template.
Creating report batch jobs
You can create a batch job with a predefined frequency that will generate and email a report as an attachment
to a pre-specified email address.
When generating an HTML report in a batch job, you have the option of automatically converting the report to
PDF format before emailing it.
For more information about batch jobs, see Batch jobs on page 736.
Right to left support in reports
Rollbase renders text in reports from left to right (LTR). Unlike on application pages, Rollbase does not
automatically set the text direction based on the language. However, you can edit your report content to render
some or all text from right to left (RTL).
The method for supporting RTL text in a report depends on the type of report:
• Tabular report — Rollbase automatically renders text in the correct direction based on the user's language
and requires no additional configuration.
• Document template report — A document template report is based on a document template; how you
configure the text direction depends on the type of document template. See Document templates for details.
• HTML report — Use the dir attribute and the bdi element as described in Document templates to format
the text direction of the HTML content. Users can render HTML reports as PDF. To render PDF content as
RTL, use the dir attribute in the body element of the base HTML.
• JavaScript report — Rollbase automatically renders text in the correct direction based on the language used
in the report and requires no additional configuration.
• Custom report — You can define your own style for custom reports in two general ways:
342 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Reports, charts, and gauges
• To render an entire report as RTL, either select an existing stylesheet that renders text as RTL when
creating the report, or add body {direction: rtl;} in the Styling Properties area. See Selecting
a Custom Report Type on page 309 for details about adding a stylesheet and styles to a custom report.
• To render a section of a report as RTL, add the styling directly to the section. For example, you can
modify the div element of an HTML Template section to add the style attribute as shown below:
<div class='rbs-cr-htmlSection' style='direction:rtl'>
مرحبا
</div>
For more information about language support, see Language support on page 740.
Working with charts
You can use charts in Rollbase to visually represent a snapshot of your data. Charts support a wide variety of
styles: bar, column, pie, donut, and many others. Charts can periodically and automatically refresh themselves
without a complete page refresh. Some charts provide drill-down capabilities and interactivity options such as
rotation and slice movement.
Charts are responsive and are auto-scaled to fit the available space. Auto-scaling is done only if the available
space is less than the configured chart dimensions. Otherwise, the chart will always be rendered with the
configured dimensions.
Rollbase offers two engines to render charts:
• FusionCharts (based on HTML)
• Google Charts (based on HTML)
Creating charts
You create charts from an object definition page. To build or configure a chart:
1. Navigate to an object definition page, select Charts from the ribbon, and click New Chart.
The New Chart page opens:
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 343
Chapter 6: Adding business logic
2. Select one of the chart engines, either FusionCharts (HTML) or Google Charts (HTML).
3. Designate how records of a particular object will be grouped into collections (columns or slices). A set of
collections is referred to as the X Axis (this refers to a bar-style charts and can be logically extended to
other types of charts). You can create these groupings for:
• Records of the object type
• Enumeration fields (pick lists, status)
• Lookup fields (one or more related records)
• Date fields (dates can be further grouped by week, month, quarter, or year)
• Numeric fields (allows specification of a range of numeric values)
4. Specify which numeric value will be summarized for each collection. This value is referred as the Y Axis.
This value might belong to either the parent or to a related object. You can also use the count of parent or
of related records.
5. Click Next and specify the following information:
• The chart style
• A name for the chart
• Labels for the X-Axis and Y-Axis (not used for pie and donuts charts)
• The chart width and height in pixels
• Fit to Container Size — When selected (the default), the chart is responsive and is auto-scaled to fit in
the available space. Auto-scaling is done only if the available space is less than the configured chart
dimensions. Otherwise, the chart will always be rendered with the configured dimensions. Deselect this
property to disable responsiveness for the chart.
6. Optionally specify the following if you selected FusionCharts as your chart engine:
• Select Chart Background if you want this chart to have a background color or image. If you choose to
have an external image (GIF, JPEG or PNG only) as a background of the chart, you must browse and
upload an image. You can then select the required Background Opacity and Display Mode.
• Select Chart Font Color if you want to change the chart's default font color. You must ensure you choose
a contrast font color that will be clearly visible on the chosen chart background color.
344 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Reports, charts, and gauges
• Select Canvas Background Color if you want to add a background color to the chart canvas. In addition,
you can also set the canvas color opacity.
Note: The Canvas Background Color property is not available for Doughnut (2D and 3D), Pie (2D
and 3D), and Grid charts.
• Select Animate Chart if you want HTML-based animation for this chart when available.
• Select Auto-Refresh Chart if you want this chart to be automatically refreshed without manually reloading
the page or report where the chart resides.
• Select Disable Drill-Down if you do not want to allow drill-down to records in chart columns or pie slices.
• Select View for Drill-Down to specify the view to use to display the drill-down data.
• Select Show Chart Logo if you want to add a logo (GIF, JPEG or PNG only) to the chart. In addition,
you can also set the logo scale, opacity, and position. You can also point the logo to some external url
by providing the Logo Hyperlink.
7. Specify the Chart Columns setting for the selected collections:
• For numeric fields, select the range and width of each collection.
• For date fields, select the date's interval (week, month, quarter, or year) range.
• In the Compute What field, specify what is to be computed for records that fall in a particular collection:
total, average, or percentage of this collection relative to all collections total.
• In the Data value color property, specify the color for the data value. Note that this will work in conjunction
to the Show Columns Values property. You can specify the color for the data values only if Show
Columns Values property is selected.
Note: The Data Value Color property is not available for Doughnut (2D and 3D) charts.
• In the Data plot fill type property, specify the data plot fill type (color/gradient) and you can choose to
turn on/off the Show border for data plot.
Note: The Data plot fill type property is not available for Column 3D, Doughnut (2D and 3D), Line, and
Pie (2D and 3D) charts. While, the Show border for data plot property is not available for Line charts.
Warning: To preserve system resources, the total number of collections per chart is limited to 200. If you
select conditions that generate too many collections, not all collections will be displayed and Rollbase will
generate a warning message. Hiding empty collections by checking the Hide empty columns check box
will improve the visual representation of your chart but will not remove the limitation on the total number of
displayed collections.
8. Optionally use Chart Filters to filter and render different types of data on your chart.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 345
Chapter 6: Adding business logic
Using charts
To make a chart available for viewing on a page, use the page editor to add the chart component to an empty
section on a generic or object list view page. This will display the selected chart on that page, along with a
toolbar:
From the section containing the chart, you can do the following:
• Click the reload button next to the section title to reload the chart.
• Select another chart from the first drop-down menu.
• Select Edit this Chart from the chart actions menu to edit the chart.
• Select Create New Chart from the chart actions menu to edit the chart.
• Select Clone this Chart from the chart actions menu to clone the chart.
• Click Filter to dynamically filter data visualized in the selected chart.
• Right-click the chart and select Download SVG Vector Image to save an XML-based image of the chart.
The administrative permission Manage Charts is required to edit, create, and clone charts.
346 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Reports, charts, and gauges
An example FusionChart:
An example Google chart:
Debugging charts
Because Rollbase generates the underlying functionality for charts, they can be difficult to troubleshoot. On
Rollbase Private Cloud, an administrator of the master tenant logged into a customer tenant can enable logging
of the underlying SQL queries. See Enabling logging for charts and views on page 829 for details. You can use
the log file to see if the expected queries are being executed. Since logging can delay rendering of the charts,
it should only be enabled temporarily for debugging purposes.
Working with gauges
You can use a gauge in Rollbase to visually represent a single numeric value computed using a JavaScript
formula. Gauges resemble familiar devices such as a car's speedometer or an electronic scale. Rollbase
supports several different gauge types for various visual effects. Gauges can periodically and automatically
refresh themselves without a complete page refresh.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 347
Chapter 6: Adding business logic
Creating and configuring gauges
To create a gauge:
1. Navigate to an object definition page, select Gauges from the ribbon, and click New Gauge.
2. Select a Gauge Style:
3. Type a Gauge Title for the gauge.
4. Select a Gauge Size: Large, Medium, or Small.
5. Select Show Background Border to show or hide the border for the gauge container.
Note: The Show Background Color property is not available for the following gauge styles.
6. Select the Annotation Type for the gauge. This can be Number, Percent, or one of several currencies.
7. Select the Min Value and Max Value to represent the beginning and end of the gauge's display range.
Rollbase renders the computed value by positioning the gauge's arrow relative to these values. Optionally
type a Label for each of these values.
8. Optionally set a Lower Range Color, Middle Range Color, and an Upper Range Color to customize the
data range color for lower range, middle range and upper range based on the context in which the gauge
will be used. Rollbase uses the First Midpoint Value and Second Midpoint Value values to visually indicate
the gauge's lower, middle, and upper range values.
Note: The Data Range Color properties are not available for the following gauge styles.
9. Optionally set a Plot Fill Color.
Note: This field is available only for the Vertical Linear Gauge.
10. Specify the JavaScript formula to compute the gauge's value. If you use the gauge to visualize data for a
particular record, use tokens from that record and its related records. If you use the gauge is to visualize
data from a list of records, use a loop to iterate over records, compute and return a final value. You can
348 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Multi-currency support
also use the Rollbase Query API in gauges. For more information about formulas, see Formulas on page
208.
Using gauges
As with other UI components, you can use the page editor to add one or more gauge components to a section
on a generic, object, or view page. There is no further configuration necessary to start viewing your computed
data with professional looking gauges.
You can place up to four gauges in a row in a single section.
Using the controls above each gauge component, you can:
• Refresh a gauge component.
• Edit a gauge component.
The administrative permission Manage Charts is required to create and modify gauges.
Note: Avoid using the template #LOOP in a gauge's formula because it might lead to inefficient computations.
Instead, try using group functions or the query API. For more information about formulas, see Formulas on
page 208.
Multi-currency support
Rollbase supports conversion between monetary values in different currencies. It is common for businesses
to keep their accounting books in one currency (let us call this the base currency), while sending and receiving
money in several other currencies. In addition, exchange rates between currencies tend to change over time.
Rollbase provides a multi-currency framework for all customers.
The following illustrates multi-currency functionality:
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 349
Chapter 6: Adding business logic
Although the Base Currency field is read-only, you can use it in formula fields and triggers, as well as to calculate
totals in list views and reports. Modifying an exchange rate on a particular date will not affect any Base Currency
values that already have been calculated because, unlike formula fields which are dynamically computed, Base
Currency fields are calculated and stored in your database. However, when you edit and save an existing
record, this value will automatically be updated using the currently available exchange rate corresponding to
the assigned rate date.
To start using multi-currency, follow these steps:
1. Set up currency codes on page 350
2. Set up exchange rate on page 351
3. Enabling multi-currency attribute on the object definition on page 351
4. Money amounts in base currency on page 352
Set up currency codes
When you set up currency codes, the currencies you specify will be shared picklist items available to end-users.
To set up currency codes, navigate to the Currency Codes page from Setup Home > Administration Setup
> Currency Codes. Enter a list of the currency names and currency codes you want to support. Mark the
currency to use as the default by prefixing it with the symbol {D}. For example:
{D}US Dollar|USD
350 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Multi-currency support
Set up exchange rate
To manage exchange rates, a user must have a role of Administrator or Manage Exchange Rates
administrative permission. Set exchange rates manually by navigating to Setup Home> Administration Setup
> Exchange Rates. On the Exchange Rates page, select a date and click Next. Enter exchange rates as
decimal numbers values of the selected base currency and supported currencies. By entering the exchange
ratio between one unit of foreign currency and one unit of base currency, the inverse is handled for you
automatically. For example, defining a EUR / USD ratio as x also defines a USD / EUR ratio as 1/x.
You can also use the SOAP API to store exchange rates (see Rollbase SOAP Methods on page 1322). If you
will be using multi-currency capabilities on a daily basis you might consider building an automated integration
with another web service to retrieve exchange rates and populate them in Rollbase for you.
Enabling multi-currency attribute on the object definition
If you enable the Multi-Currency attribute on objects, Rollbase adds two new fields:
• Currency Code, to specify the type of currency for a particular record such as an invoice.
• Rate Date, used to determine the date for the exchange rate calculation, which is the current date by default.
This field ensures that the exchange rate calculation for a record does not change over time as the exchange
rates change.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 351
Chapter 6: Adding business logic
Money amounts in base currency
You can optionally create a Base Currency field that corresponds to each a new or existing Currency field
as desired. In this case, the Currency field holds the actual currency amount determined by the Currency
Code field at the record level and the Base Currency field holds a read-only amount that Rollbase calculates
by converting the value from the Currency field into the base bookkeeping currency. The Rate Date field, as
explained above, determines the date of conversion.
For example, an invoice record has the following field values:
• Currency Code: British Pound
• Rate Date: 08/18/2015
• Amount (editable): 2000.00
• Base Amount (read-only): $2,894.40
The exchange rate on 08/18/2015 is set to: GBP / USD = 1.4472. Rollbase calculates and displays the value
for the base amount (which is configured to use USD) as $2,894.40.
Surveys and quizzes
Surveys provide a way to quickly assemble groups of questions and to process answers from users or portal
users. Survey questions can include ranking criteria to act as online quizzes or tests. Surveys allow you to
associate different groups of fields with records of the same object. The diagram below illustrates how surveys
work. You create the questions, the survey, and optional ranking criteria. Users and portal visitors can take the
survey; Rollbase saves the answers and calculates the score.
Enabling and creating surveys requires the following components:
352 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Surveys and quizzes
• An object with the Survey attribute enabled. Survey records contain the questions, which you can add
directly to the record or from a question library. When you create an object with the Survey attribute, Rollbase
creates a special Take Survey page. This page displays survey questions to end-users and can be edited
and cloned just like any other Rollbase page. You can configure this page to include a particular survey.
The page properties include a template token. You can add a URL to any template on an application or
portal page using the Surveys section in the template helper. The Survey Pages group in the template
helper provides you with a merge field token that will be resolved into the URL of the Survey page. You can
use this URL in links or in an HTML button control.
• The User object (or another object you use to manage survey takers) must have the Survey Taker attribute
enabled. The Survey Answers component lists all surveys taken. For each survey, it displays a list of
questions and the answers users provided. If ranking criteria was set for a particular question, the system
calculates and displays an assigned score along with maximum and minimum possible scores. Minimum
score is only used when negative ranking was specified. Otherwise the minimum score is 0. The object
fields Survey Score and Rank (score as a percentage of the maximum score) can be used to set up triggers
to execute business logic and provide automation based on survey results.
Creating a survey
Follow these general steps to create a survey:
1. Create a new object with a Survey attribute or enable the Survey attribute on an existing object. If you
create a new object with the Survey attribute, Rollbase adds a Questions option to the page menu
automatically. If you enable the Survey attribute on an existing object, you can add the Questions option
by editing the object tab as described in Enabling surveys on an existing object on page 354. The Questions
menu option (shown below) allows you to create a questions library. Rollbase saves survey questions in a
shared library that can be accessed from any object that has the Survey attribute.
2. To distribute the survey to end users in your tenant, make sure the Survey Taker attribute is enabled on
the User object.
3. Create survey questions as described in Creating a question library on page 357 and Adding questions to a
survey on page 356.
4. Distribute the survey link in one of the ways described in Survey pages and links on page 358.
5. See how survey takers responded as described in Collecting survey answers on page 359.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 353
Chapter 6: Adding business logic
Enabling surveys on an existing object
To create surveys, one or more objects in your tenant must have the Survey attribute enabled. If you create
a new object with the Survey attribute, Rollbase adds a Questions option to the page menu automatically. To
enable the attribute on an existing object, and add the Questions option to the page menu, follow these steps:
1. Enable the Survey attribute:
a) Open an application in which the object is used.
b) From the application menu bar, click the object's tab.
c) From the Page Options menu, select Object Definition:
Object Definition is accessible from all application pages.
d) Click Edit.
e) Scroll to the Advanced Attribute section and click the Survey attribute box.
f) Click Save.
2. In the object definition, add the Question option to the page menu:
a) Navigate to the application setup page. For example, from the application switcher, select the Application
Settings icon.
b) Navigate to the Tabs section.
c) Click the name of the tab for the object with the Survey attribute.
A page displays that lists properties and menu items:
354 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Surveys and quizzes
d) Click New Menu.
The New Menu page opens:
e) For Menu Name, enter Questions.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 355
Chapter 6: Adding business logic
f) From the Menu Type list, select Questions.
g) Click Save.
The Questions menu item should now be available from the object tab page menu.
Adding questions to a survey
To create a survey, you need to create a record of an object with the Survey attribute and give it a name. The
view page for the record contains a Questions section. Use the page editor to add this to a new section if the
page doesn't contain it.
The Actions menu contains options to:
• Create a new question.
• Select from existing questions in a and add them (or a copy of them) to the survey. You can attach questions
from the library directly or you can create a copy (clone) of each question. In the latter case, if you modify
the selected question, it will not affect the version in the questions library.
• Change the order of the questions. Questions are grouped by categories and ordered by the selected order
number.
• Preview survey questions as they'll appear to the user taking the survey.
From the Action column you can:
• Edit a survey question.
• Permanently delete a question from all surveys.
• Remove a question from the current survey.
356 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Surveys and quizzes
Questions can be any of the following types:
• Text: Users can enter any combination of characters. You can optionally define an input mask to enforce
certain kinds of input.
• Text Area: Users can enter multiple lines of text. You can optionally enable a rich text editor so users can
enter text as formatted HTML.
• Picklist: Users can select a value from a list of values you define.
• Picklist (Multi-Select): Users can select any number of values from a list of values you define.
• Radio Buttons: Group of radio buttons with mutually exclusive selection.
• Checkbox: Users can select a Checked (true) or Unchecked (false) value.
• Group of Checkboxes: Group of checkboxes with multiple selections.
• Currency: Users can enter a dollar or other currency amount.
• Date: Users can enter a date or pick a date from a calendar popup.
• Date/Time: Users can enter a date and a time, or pick a date from a calendar popup (when a date is selected
from the calendar popup, that date and the current time are entered into the Date/Time field).
• Email: Users can enter an email address which is checked to ensure that it is a valid format.
• Integer: Users can enter any number (without decimals).
• URL: Users can enter any website address.
Each type of question has specific associated properties. For instance, text questions have the following
properties:
• Question label
• Short label
• Category
• Whether an answer is required for this question
• Whether this question should be available in any application which includes the Survey object
• Size of the HTML input box
• Keywords: You can specify keywords and their ranking in the range from -1000 to 1000. A score calculator
will award scores for specified keywords in the answer.
Creating a question library
A question library saves a set of questions that can be used in multiple surveys. The questions library allows
you to organize questions in categories and provides a default Generic category. You can create new categories
and rename or delete existing categories. However, you can only delete categories that have no questions
associated with them.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 357
Chapter 6: Adding business logic
Survey pages and links
The Take Survey page for an object with the Survey attribute allows you to configure surveys and identify the
link to provide to survey takers. Access the Take Survey page from the object definition:
Click Config to set:
• The number of columns in which to display questions (1, 2, or 3).
• The default survey record used for this page. The URL to a Take Survey page can include the ID of a
particular survey. If not, the default Survey record selected in the Config page will be used. If this URL
parameter is not included, Rollbase will use last survey record viewed or accessed.
Add a link to the Take Survey page to any template on an application or portal page using the Surveys section
in the Template Helper. The Survey Pages group in the Template Helper provides you with a merge field
token that will be resolved into the URL of the page. You can use this URL in links or in an HTML button control.
358 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Surveys and quizzes
Taking a survey
End users following the link you supply will be directed to the Take Survey page. Survey questions display in
sections by category.
Answers to survey questions are subject to validation rules similar to those for object fields: required questions
must be answered, integer questions must be parsed as integers, etc.
Collecting survey answers
Rollbase saves survey results. You can view them along with the record associated with the person taking the
survey. On the record view page you will find a Survey Answers component use the page editor to add it if it
is not automatically added to your view page.
Using surveys on portals
Surveys in portals can be a useful tool, for example, to collect customer feedback. Portal visitors are required
to log in to take a survey.
To add surveys to your portal:
1. Verify that the object type associated with the survey has the Survey attribute.
2. Create a Survey, create a survey record, and add survey questions to the record.
3. Create an object type with both the Survey Taker and Portal User attributes. See Creating a portal user
on page 541.
4. Create some records of the Portal User object type.
5. Create a portal page of the type Login Form and associate it with the Portal User object type. See Creating
portal pages on page 528.
6. Create a portal page of the type Take Survey. See Creating portal pages on page 528.
7. Assign the survey record to the Take Survey portal page. The page will automatically populate the portal
user's Answers field with the survey results.
8. Assign the Take Survey portal page as a destination page from another portal page (for example, from the
Login Form).
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 359
Chapter 6: Adding business logic
360 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
7
Customizing the user experience
You can customize the user experience by controlling what users see on application pages and how they
navigate through the application. Additional files required for customization, such as images and cascading
style sheets, can be uploaded as hosted files. You can select a built-in theme for an applications and customize
the look and feel of your application. Portals allow you to create a user interface and host it yourself.
For details, see the following topics:
• Pages, the page editor, and grid controls
• UI Blueprints
• Setting a Different UI Blueprint on Mobile Devices
• App Preview
• Adaptive user interface
• Responsive user interface
• Working with views
• Working with themes
• Record List Options, Mobile and Tablet Support
• Pagination Control, Responsive Image Fields, and Custom Reports
• Enhanced Smart Images, Notifications, and Others
• Improved Editing Capabilities
• Record View and Record Edit Page Toolbars
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 361
Chapter 7: Customizing the user experience
• Performance Improvements
• Improved Recycle Bin, Kendo UI Library, and Settings Record
• Filtering Features and Notification for Pending Changes
• Programmatic client-side customization
• Rollbase portals
• Hosted files
Pages, the page editor, and grid controls
When you create application objects, Rollbase automatically creates a set of pages that give end-users the
ability to view, create, update, and delete records. You can customize pages and their components — such
as sections, tabs, and fields — with HTML and JavaScript. You can also create your own pages with custom
appearance and behavior.
Rollbase uses Telerik Kendo UI, a responsive user interface framework, to create application pages. The
resulting pages automatically adjust themselves for different screen widths and allows you to build one application
with a modern look for all devices from full-screen browsers to smart phones.
Application page types on page 82 introduces the default pages Rollbase creates for you. When you create
an object and associate it with an application, by default Rollbase adds a records list page for that object to
the application menu bar. Users see other pages, such as the view page when they click a record, or the new
record page when they click New. You can customize the user experience by choosing which actions to expose
to users and what those pages contain. For example, you can add a grid component to a page. A grid component
allows users to create and edit data in related records while working with a parent record.
There are two general types of pages:
• Object pages — Pages associated with objects, including pages that list records and pages that allow you
to create or edit records.
• Generic pages — Pages that are not associated with objects.
Creating tabs and pages
You can create new pages for your applications. To create a page, create a tab; Rollbase automatically creates
an associated page for the tab.
To create a a tab and its associated page:
1. Do one of the following:
• On an application setup page, click Tabs in the ribbon and click New Tab.
• On an application page, click plus on the application menu bar, select A new Tab, and click Create.
The New Tab page opens:
362 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Pages, the page editor, and grid controls
2. In the Tab Name field, type a name for the tab.
3. From the Tab Type drop-down field, select one of the following:
• Generic to create a generic tab and page
• Object to create an object tab and page
• Web to create a Web tab and page (allows you to embed other Web sites and Web applications)
4. From the Parent Tab drop-down field, select one of the following:
• None if you want the new tab to be a top-level tab
• An existing tab under which the new tab will be a menu
See Application tabs and menus on page 91 for information about locating and editing tabs.
5. For the Show In property, select the device types you want to display this tab. By default, tabs display in
all device types.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 363
Chapter 7: Customizing the user experience
6. For the Icon type property, you can customize the icon for the sidebar tab when using the Modern - Vertical
Menus UI blueprint.
• Default — The icon in the sidebar tab are rendered with the first letter of the name of the tab.
• Font icon — The icon in the sidebar tab is rendered with a font icon selected from Bootstrap Glyphicons
or Font Awesome icons. Progress recommend Font Awesome icons, which are SVG icons that work
well with resizing for different font size and work well with different themes.
• Custom — The icon in the sidebar tab is rendered as the selected custom image.
7. If you are creating an object page, select the object for the page from the Object drop-down field. When
you create a new object page, the page is a record list page and by default will contain a list of records.
8. If you are creating a Web page, type the URL for the Web page or application you want to display in the
Link URL field.
9. Optionally enter a description for the tab in the Description field.
10. Select the application(s) to which to add the tab.
11. Optionally set permissions for the tab. The Administrator role and roles that have permission to access
each selected application are preselected.
See Access control on page 647 for information about permissions.
12. Click Save.
Rollbase creates the tab and its associated page.
Managing object pages
Most pages are associated with objects. See Managing generic pages on page 367 for information about
managing generic pages.
From an object view page, you can see the pages associated with that object by clicking Pages in the ribbon:
364 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Pages, the page editor, and grid controls
The object's pages are displayed in a table:
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 365
Chapter 7: Customizing the user experience
From this table, you can click one of the following links in a page's row:
• View — Opens a pop-up window displaying a preview of the page. For View, Edit, and Status pages,
opens a selector page where you can select the record to view in the preview.
• Edit — Opens the page editor.
• Clone — Creates a new version of the page and opens it in the page editor.
• Del — Deletes the page. This options is only available for cloned pages.Deletes the page. This option is
not available for pages automatically created by Rollbase.
• Synch — For New, Edit, and View pages, opens the Synchronize page, which allows you to synchronize
the page with another page in the application, meaning all of the page components will be the same on both
pages. This is useful, for example, when you have edited an Edit page to add new field components to it
and you want to update the New page to contain the same components. Click Synch next to the Edit page,
select the New page, and click Save.
• Properties — Opens the Page Properties page, which allows you to edit the page's properties, the heading
for each of the page's sections, and other properties depending on the page type. It also allows you to define
HTML event handlers on page 513 for the page (not available for Selector pages). The screen below shows
the Page Properties page for an Edit page:
366 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Pages, the page editor, and grid controls
• Page name — Opens a page that displays general information about the page, such as its type, its template
token, and when it was last updated.
Managing generic pages
A generic page is not associated with an object. Use generic tabs and pages to create custom pages for your
applications. You can use the page editor to add components to the page.
To view, edit, or set the properties of a generic page, navigate to the associated generic tab in one of the
following ways:
• From the Setup home page, click Tabs under Application Setup and click the tab name.
• Open the setup page for an application that includes the tab, click Tabs in the ribbon, and click the tab
name. The Tab view page opens and displays options for accessing the generic page:
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 367
Chapter 7: Customizing the user experience
Click View to open a pop-up window with a preview of the page.
Click Edit to edit the page in the page editor. Properties for a generic page include:
• Columns — A generic page can have one or two columns.
• Render Mode — A generic page with two columns can be Responsive or Fluid. When Responsive is
selected (the default):
• On desktops and on tablets in landscape mode, the page will display two columns.
• On tablets in portrait mode and on smart phones, the page will display one column.
When Fluid is selected, the page is not responsive to different screen sizes.
See Editing pages on page 369 for information about the page editor.
Click Properties to view and edit page properties.
368 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Pages, the page editor, and grid controls
Editing pages
A page specifies the contents of an application page. Application pages always contain an application tab, an
application menu bar, a header and footer, and certain components such as search and the page tools menu.
See Application page components on page 30 for information about these components.
In addition to the common components described above, an application page contains:
• Components — A component is a user interface control or field. A component can also be a section of
HTML or JavaScript. Components available to a page depend on the page type. See Page components on
page 94 for a description of each component and where it can be used.
• Sections — A section is an area of a page that contains components. Some components, such as charts,
can only be placed in an empty section. A section has a title that you can edit.
• Columns — A section can contain up to four columns. The rendered page automatically adjusts its display
of the columns based on the width of the screen.
The page editor allows administrators to specify which components a page contains, to control the layout of
components within the page using sections and columns, and to configure each component. The screen below
shows the page editor for an edit record page. Available components are listed by category in the left sidebar:
The general steps for editing a page are:
1. Navigate to the page and open the page editor:
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 369
Chapter 7: Customizing the user experience
• For a page associated with an object, navigate to the Pages table on the object view page and click Edit
next to the page name. See Managing object pages on page 364 for details.
• For a generic page, navigate to the tab view page for its associated tab and click Edit. See Managing
generic pages on page 367 for details.
• From any application page, select Design This Page from the Page Options menu.
2. Drag the desired sections and components from the left sidebar onto the page.
3. Configure the sections and components.
4. Save the page. You can also save and synchronize the page, which gives you the option to apply the
changes you just made to other pages for this object.
Adding and configuring sections
Sections allow you to organize page components into different groups and columns. Add a section to a page
by dragging the New Section component from the left sidebar onto the page.
Configure a section by opening the Properties menu next to the section title:
Section properties control the section title, the number of columns, and other display properties.
370 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Pages, the page editor, and grid controls
Section properties include:
• Section Title — The title displayed at the top of the section
• Tab — For record view pages only, the tab associated with the section. By default, record view pages
include tabs to view record information and to view system information, and you can associate each section
with one of these tabs and create new tabs.
• Columns — The number of columns in the section. By default, sections on the page are aligned from top
to bottom in one column. You can configure a section to contain up to four columns and organize components
by dragging them from one column to another.
• Style — Specifies whether the Section Title is displayed on the application page and whether there is a
border around the section.
• Collapsible — Specifies whether a user can collapse the section on the application page.
• Default New Fields Section — When checked, any new fields added to the object will appear in this section
of the page. A page can only have one default new fields section.
• Show In — Specifies whether this section is displayed on desktops, tablets, and/or smartphones. Displays
on all devices by default. Deselect a device type if you do not want the section displayed on it. The icons
representing devices appear in the following order: desktop, tablet, smart phone.
You can use the section menu at the top right corner of a section to move the section on the page or to delete
the section:
Adding and configuring components
Add a component to a page by dragging it from the left sidebar onto a section. Available components depend
on the page type. See Page components on page 94 for information about which components are available
for each page type. Some components, such as view components and charts, are required to be placed in an
empty section.
Components have configurable properties. Each type of component has its own set of properties.
Configure a component by opening the drop-down menu to its right. The screen below shows the properties
of a text field:
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 371
Chapter 7: Customizing the user experience
A view component displays a list of records. The screen below shows the properties of a view component. You
can select the view to use from the Use List View drop-down menu:
372 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Pages, the page editor, and grid controls
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 373
Chapter 7: Customizing the user experience
Other components you can add to a page include:
• Lookup fields — Allow users to select a related record. See Relationships between objects on page 148 for
information about configuring lookup fields.
• Charts — Allow you to visually display a snapshot of data. See Using charts on page 346 for information
about configuring charts on a page..
• Gauges — Allow you to visually display a single value. See Using gauges on page 349 for information about
configuring gauges on a page.
• HTML components — Allow you to customize the display of a page. See Adding an HTML component to
a page on page 187 for details.
• Script components — Allow you to add JavaScript formulas to a page. See Adding a script component to
a page on page 187 for details.
• Detailed search components — Allow you to filter records by a set of preconfigured fields and operands.
See Detailed search on page 374 for details.
• Embedded quick create components — Allow a user to create a single related record while creating a core
record. See Embedded quick create on page 376 for details.
• Related records components — Lists related records and allows a user to create, attach, delete, and perform
a number of operations on related records. See Related records components on page 154 for more information.
• Page tabs — Allow you to organize page sections into different visible sets for complex pages. See Page
tabs on page 378 for details.
• Grid controls — Allow users to create, update, and delete a group of related records while editing a parent
record. See Using grid controls to manage multiple records on page 383 for details.
Detailed search
The detailed search component allows the filtering of records by a set of preconfigured fields and operands
(equals, greater than, etc.).
Use the page editor to add a Detailed Search component to a generic, list, or search results page. It can only
be added to an empty section.
374 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Pages, the page editor, and grid controls
Configure the detailed search component after saving the page by clicking Config in the Pages table on the
object view page for that page. The Configure Search Component page opens:
Configure the component by selecting:
• Which search results page to use to display results (if you have multiple pages)
• How many columns use to arrange filters
• Whether or not to hide the keyword search text box
• Whether to filter results by date intervals
• Whether to use AND (all fields) or OR (any field) logic
• Fields and available operands to appear in the detailed search component
• For text boxes: the size in columns (Defaults to 30)
• For text multi-select picklists: the size in rows (Defaults to 4)
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 375
Chapter 7: Customizing the user experience
The configured component allows users to quickly filter records by selected values:
Embedded quick create
This component allows a user to create a single related record while creating a core record. Unlike grid
components, this embedded panel uses the full quick create page and renders all fields from that page as a
part of new record page. This way, fields from core and related objects are essentially mixed on one page. The
embedded quick create component is only available on new record pages where the object type for the new
record has one or more relationships.
To use embedded quick create:
1. Open the page editor for a new record page and drag the Embedded Quick Create component from the
left sidebar to a new section or to an existing section.
2. Save the page.
3. Navigate to the page and click Config to select options for the component:
• Record to be Created - The related object for which to create the record.
• Using Page - The Quick Create page to use. You can use the automatically created page or you can
clone the page and create a new version of it.
• Component Name - A unique name for the component. In the page's HTML, this name will be appended
to all field names used by this component.
376 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Pages, the page editor, and grid controls
4. The new record page will contain all of the sections and components from the selected Quick Create page
rendered as part of the main page:
The embedded quick create component performs the same validation operations as the selected Quick Create
page. The resulting record will have a relationship with the newly created core record.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 377
Chapter 7: Customizing the user experience
Page tabs
Page tabs visually separate components on pages. They are different from application tabs. Application tabs
appear on the application menu bar, while page tabs are components of an application page and are associated
with page sections.
The record View page that Rollbase creates for you, has tabs. You can add tabs or rearrange them and you
can specify which device(s) they render on. It is also possible to add tabs to New record and Edit record pages,
but you must enable tabs on the page first. The example below shows a record View page with the tabs Rollbase
creates by default, Title Info and System Info.
Enabling tabs on New and Edit pages
Before you can add page tabs to a New or Edit page, you have to enable tabs for that page. Follow these steps
to enable page tabs:
1. Open the page editor on the page on which you want to enable tabs.
2. Click the menu next to the page title and select Enable Tabs:
378 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Pages, the page editor, and grid controls
3. The first tab, named Tab 0, and a button to add tabs will appear:
Tabs are enabled for the page. When tabs are enabled, each section on the page is associated with a tab. The
first tab, Tab 0, is associated with the first section of the page by default. You can associate a section with a
tab in the section's Properties menu.
Adding page tabs
You can add multiple tabs to a page and associate each tab with one or more sections on the page.
To add a page tab and associate it with a section:
1. Open the page editor for the page on which you want to add page tabs.
2. Click +Add Tab. A new page tab appears to the right of all other page tabs.
3. Open the tab properties, name the tab, and optionally reposition the tab.
4. In the section you want to associate with the new tab, open its Properties menu and select the tab from
the Tab drop-down field:
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 379
Chapter 7: Customizing the user experience
The tab is now associated with that section. Note that you will only see a section in the page editor if its
associated tab is selected. Use Page tab properties on page 382 to move a tab, specify which device(s) it will
render on, or delete it.
The screen below shows the page editor open on an edit record page with the Edit Title tab selected:
380 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Pages, the page editor, and grid controls
The screen below shows the page editor open on the same page with the View System Info tab selected:
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 381
Chapter 7: Customizing the user experience
The screens below shows the resulting application page:
Page tab properties
You can edit the following properties of a page tab:
• Tab Name — The name of the page tab. If the tenant has additional languages configured, you can add a
tab name for each supported language.
• Move Left — When there are multiple page tabs, move the tab to the left.
• Move Right — When there are multiple page tabs, move the tab to the right.
• Show In — Select the device(s) on which to display the page tab. By default, page tabs are displayed on
all devices.
You can also delete the page tab.
382 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Pages, the page editor, and grid controls
To access page tab properties, click the drop-down menu next to the tab name:
Using grid controls to manage multiple records
Grid controls allow users to create, update, and delete a group of related records while editing a parent record.
Grids enforce user permissions. For example, a user with only view permission would not be able to create or
update records. See Access control on page 647 for more information about permissions.
You can add a grid to the New, Edit, or Status pages where objects have the following types of relationships:
• A parent object that has a one-to-many relationship with a child object, such as a purchase order might
have to line items. The grid will display the related records on the "many" side.
• Both objects in many-to-many relationships.
The following screen illustrates a grid control in a room reservation system:
You can add a grid control to a page when creating a relationship, or you can add a grid control to an existing
page using the page editor. A grid control and a lookup field for the same related records cannot exist on the
same page. To add a grid control to a page with a lookup field, you must first remove the lookup field. See
Relationships between objects on page 148 for more information about lookup fields.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 383
Chapter 7: Customizing the user experience
Rollbase 4.3 introduced a revised grid control implementation. See Revised grid control for New UI for more
information.
Grid Control Examples and API on page 1073 describes how to customize grid behavior using the client-side
AJAX API.
See the following topics for more information about grid controls:
• Adding a grid control to a page on page 384
• Configuring a grid control on page 385
• Using a grid control on page 388
Adding a grid control to a page
Follow these steps to add a grid control to an existing page:
1. Open the page in the page editor.
The page editor opens the definition of the page.
2. If the page already contains a lookup field for this relationship, remove it:
a) Right-click the lookup field.
b) Select Remove.
c) Delete the empty section by selecting Delete from the menu at the top right corner of the section.
3. Drag a New Section from the left sidebar and drop it in the location where you want the grid control to
appear on the page. Optionally edit the Section Title in the section's Properties menu. See Adding and
configuring sections on page 370 for details.
4. From the Available Components Grid Fields section of the left sidebar, select Grid Control and drag it
to the new section as shown in the example below:
5. Click Save or Save and Synchronize:
• Save applies your changes to the current page.
• Save and Synchronize gives you the option to apply the changes you just made to other pages for this
object.
Next, configure the grid component as described in Configuring a grid control on page 385
384 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Pages, the page editor, and grid controls
Configuring a grid control
Follow these steps to configure a grid control:
1. Open the Configure Grid Control page in one of the following ways:
• Navigate to the page containing the grid and click Configure Grid:
• Navigate to the Pages table in the object view page and select Config next to the page containing the
grid control:
The Configure Grid Control page opens.
2. From the Relationship drop-down, select the relationship for the records you want the grid to display.
3. Click Next. The Select Fields for Columns of Grid page appears.
4. From the Available Columns, select the fields you want to appear as grid columns and use the arrows to
move them to the Selected Columns list. Optionally, reorder the columns using the up and down arrows.
Although, you can use most field types in a grid component, there are some limitations. For example, you
cannot use filtered lookup fields.
5. Click Next.
The grid control configuration page appears:
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 385
Chapter 7: Customizing the user experience
6. Select the following settings as needed:
• Select the Required in Grid checkbox for fields to make them mandatory.
• Select Read Only for fields to ensure that these fields provide no write permissions to the users. This
operation will have no effect for the fields selected as Required in Grid.
• From the Layout dropdown, select the required grid control layout — Tabular or Responsive. This
option is applicable only for the New UI. The Tabular layout is selected by default which enables users
to edit related objects like in a spreadsheet.
• Check the Enable field-level help for this grid control to enable field-level help.
Note:
• Enable field-level help for this grid control is reflected in the grid only when the Enable field-level
help for this application checkbox is selected at the application level.
• The field-level help icon appears next to a field column header in a tabular layout and next to a field
in a responsive layout.
• Optionally, specify sorting for columns.
• Configure Lookup fields for related records:
• Choose Selector or Picklist style from the Applications drop-down menu.
386 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Pages, the page editor, and grid controls
• Select Enable Quick Create to create a related record using Quick Create pop-up.
• From the Use List View drop down, select the view to display the related records.
• Optionally, specify custom JavaScript code to be executed when a grid row is added, updated, or deleted.
For more information, see Grid Control Examples and API on page 1073.
7. Click Save.
Responsive Layout
The Responsive layout option enables users to edit the related objects as inline forms. Each grid row is housed
in its own panel with a responsive layout as depicted below. This feature offers better support for mobile devices
and tablets.
Each grid row can be collapsed or expanded individually. In addition, to expand/collapse all rows in one
command, use the widget at the top right of the grid section.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 387
Chapter 7: Customizing the user experience
Using a grid control
As shown in the following screen, a grid control enables you to add, attach, edit and delete records. You can
also configure a grid control.
With appropriate permissions, you can perform the following operations on a grid control.
• To add a new related record, click + on the grid toolbar.
• To delete a record, select a record and click Delete. This deletes the record from the system. However,
when attaching a record, attempting to delete the record will not delete the record.
• To modify a field, click in the field and type the new data.
• To configure the grid, select the Configure Grid icon.
• To attach a record to the Grid control on the record edit and create pages, click the record selector (magnifier
icon) on the Grid control toolbar. The record selector page appears with the list of existing records (i.e., the
records of the related object not already attached to the current record). Select a record to attach it to the
Grid. The attached record can also be updated during the attach flow.
Rollbase saves changes to each related record in the grid when you save the page. If an error occurs, Rollbase
displays the error messages for the grid control.
After a successful save, a confirmation message appears displaying the number of line items created, updated,
deleted and attached.
This topic described basic grid functionality. You can add logic as described in Grid Control Examples and API
on page 1073.
Revised Grid Control
Rollbase provides the option to display related records on New, Edit, and Status pages.
388 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Pages, the page editor, and grid controls
An administrator can enable it for the tenant on the Preferences screen:
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 389
Chapter 7: Customizing the user experience
The revised grid control:
• Scales better. For each grid column, a minimum width of 150px is enforced. Columns expand to consume
any extra space. In cases where there is a large number of columns, the grid overflows horizontally and
horizontal scrollbars appear.
• Supports bulk data entry — users can add/edit multiple records and click Save once.
• Renders field controls as Kendo widgets.
• Uses the same date and time format as date and time fields on the Edit page.
• Supports client-side validation.
• Supports URL input fields with format validation and will automatically add http:// to the beginning of the
value if not supplied. For example, if the user types progress.com into the field, it will be changed to
http://progress.com. If the user types progress into the field, an error message appears.
• Supports dirty page notifications. For example, if a user adds a new record to the grid and navigates away
from the page before saving, it, a notification appears that gives the user a chance to save their changes.
See onLeavingDirtyPage on page 1151 for more information about dirty page notifications.
• Includes client-side API enhancements. See Revised grid control: Client-side API enhancements
• Supports new custom events. See Revised grid control: New custom events
• Supports Main Lookup / Link Lookup settings in Lookup fields. A Lookup field is created for each relationship
defined in an object. For example, the screen below shows the Lookup field for the many-to-many relationship
between Project and Contact. The Main Lookup and Link Lookup properties specify that when attaching
a Contact to a Project in a grid, only the Contact records related to the Project record's related Customer
record will appear in the Selector page.
390 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Pages, the page editor, and grid controls
The following screen shows the revised grid control. The user has added three devices and Rollbase will save
all three at the same time:
Revised grid control: Client-side API enhancements
A GridControl component can now be accessed as a PageComponent object. A GridControl component
has a GridRow component for each row in the grid.
Use one of the following APIs to access a GridControl component:
• rbf_getPageComponent(componentId) — componentId is the original PageCell id of the
GridControl.
• rbf_getGridControlComponent(gridNo) — gridNo is the order in which this GridControl
component appears on the page. For example, call rbf_getGridControlComponent(0); to access
the first GridControl component on a page.
The GridControl component has the following public interface:
• addEventListener(eventType,handler) — Registers an event listener for the given event type
• addGridRow() — Adds a new grid row to the GridControl
• deleteGridRow(rowIndex) — Removes the GridRow at the specified row index
• getContentElement() — Returns a jQuery object for the root element housing the GridControl
component
• getFieldCell(rowIndex, fieldName) — Returns a jQuery object of the field container element where
the field is identified by rowIndex and fieldName
• getGridControlSectionToolbarEl() — Returns a jQuery object for the GridControl section toolbar
element
• getGridControlToolbar() — Returns a jQuery object for the GridControl toolbar element
• getGridControlToolbarEl() — Returns a Kendo Toolbar configuration object for the GridControl
toolbar
• getGridNumber() — Returns the order of the GridControl component on the page
• getGridRow(rowIndex) — Returns the GridRow object at the specified row index
• getId() — Returns the GridControl component's PageCell's ID
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 391
Chapter 7: Customizing the user experience
• getKendoConfig() — Returns the Kendo Grid configuration object for the GridControl component
• getLastModifiedField() — Returns the FieldContext object of the last modified field. See
FieldContext on page 1132 for more information.
• getMaxRowIndex() — Returns the number of grid rows in the GridControl component
• getOriginalId() — Returns the GridControl component's PageCell's originalID
• removeEventListener(eventType,handler) — Unregisters an event listener for the specified
eventType
• showGridTotals() — Computes and shows grid totals for each TotalBy column in the GridControl
component
• sumGridColumn(fieldName) — Computes and shows the grid total for the specified GridControl
column as identified by fieldName
The GridRow component has the following public interface:
• getData() — Returns GridRow data in serialized JSON format
• getField(fieldName) — Returns the FieldContext object for the specified field in the row. See
FieldContext on page 1132 for more information.
• getFieldCell(fieldName) — Returns a jQuery object of the field container element where the field is
identified by fieldName
• getFieldData(fieldName) — Returns field data in serialized JSON format
• getIndex() — Returns the row Index of this GridRow
• getRecordId() — Returns the GridRow record's record Id. The value is -1 for new GridRow records.
Revised grid control: New custom events
The revised grid control supports the following custom events:
• rb.newui.util.customEvents.rbs_gridControlFieldUpdate — Raised when the user updates
a field in the grid control
• rb.newui.util.customEvents.rbs_gridControlRowCreate — Raised when the user creates a
new record in the grid control
• rb.newui.util.customEvents.rbs_gridControlRowDelete — Raised when the user deletes a
record in the grid control
The following code registers an event for a GridControl component:
gridControlComponent.addEventListener(rb.newui.util.customEvents.rbs_gridControlRowCreate,
function ()
{ alert('Row Created'); }
);
392 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Pages, the page editor, and grid controls
Using buttons on pages
You can add buttons to view, new record, edit, or status change pages. These buttons will appear in the page
toolbar, at the top right of the application page. When a user clicks a button, the button can perform one of the
following actions:
• Run JavaScript.
• Open a URL in a new browser window.
To manage buttons, click Buttons in the ribbon on an object definition screen to navigate to the Buttons table
and select one of the following:
• Edit — Edit the button.
• Clone — Create a new button that is a clone of this button.
• Del — Delete the button.
• Button name — View button properties.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 393
Chapter 7: Customizing the user experience
To create a new button:
1. Click New Button. The New Button page opens.
2. Specify the following:
• Display Label — Enter the text that will display on the button.
• Button Name — Optionally enter the button's name (used as HTML tag "name"). Defaults to Display
Label with an underscore for each space..
• Behavior — The action to perform. Select one of:
• Run client-side JavaScript
• Open URL in new window
• Show In — Specifies whether this button is displayed on desktops, tablets, and/or smart phones. Displays
on all devices by default. Deselect a device type if you do not want the button displayed on it. Devices
are represented by icons in the following order: desktop, tablet, smart phone. The Buttons section of a
Setup Application page contains a Show In column that displays your choices.
• Toolbar Responsive Overflow Rule — Enables you to control how the buttons (custom buttons and
workflow action buttons) are positioned in relation to the overflow menu. Depending on your requirement,
you can choose one of the options from the drop-down list.
1. Always show in overflow menu — Forces the button in the overflow menu irrespective of available
space.
2. Never show in overflow menu — Forces the button in the toolbar irrespective of available space.
3. Show in toolbar when there is space — Places the button in the toolbar if there is space.If not, the
button is placed in the overflow menu. This option is selected by default.
Note: You must ensure that there is enough space on your page when you choose the Never show in
overflow menu option.
• Button Script or URL — The JavaScript template or the URL template. Both templates may include
record's tokens to be replaced with actual values at runtime. See Working with templates on page 184
for information about templates.
• Show button – Condition formula — Add a conditional formula. This conditional formula is evaluated
before adding a button to the page. The button will be added only if the evaluation results in Boolean
value TRUE.
With the condition formula feature, you can dynamically decide whether to add a button depending on
a record's workflow status field, user's role, and so on.
• Add to Pages — Select the pages to which you want to add the new button.
394 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Pages, the page editor, and grid controls
The following screen shows the properties of a Extend button that appears for a title with status as Checked
Out.
The following screen shows the button on an application page:
You can add or remove buttons from a page by clicking the Properties link for the page in the page table on
an object view page.
Customizing the header and footer
You can customize the look of application pages by adding a custom header and/or footer. You can add any
HTML, CSS, and/or JavaScript to customize the header and footer. If you want to use images or refer to a
CSS, you should upload those as hosted files first. See Hosted files on page 547 for details.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 395
Chapter 7: Customizing the user experience
You can use the same techniques to customize the sidebar for an application (see Custom sidebar on page
117) and to customize the user interface, for example, by executing custom JavaScript, you can change the
color of or hide certain Rollbase HTML elements. See Working with templates on page 184, Formulas on page
208, and Client-side JavaScript on page 1131 for more information.
Follow these steps to modify the header and footer:
1. Navigate to the application definition. For example,
a) From the application switcher, select Setup Home.
b) In the Application Setup section, click Applications.
c) Click the name of the application you want to modify.
2. From the More actions menu, select Header And Footer.
3. Enter your custom style information in HTML Header and HTML Footer boxes.
4. Click Save.
For example, the custom header and footer shown above uses a hosted graphic and locally declared
styles. The HTML Header defines my-header and my-footer classes as follows:
<style>
.my-header {
background: #eee;
margin-bottom: 10px;
padding: 10px;
margin-bottom: 25px;
font-size: 25px;
font-weight: bold;
padding: 35px;
border-radius: 5px;
background: #00b7ea;
background: -moz-linear-gradient(top, #00b7ea 0%, #009ec3 100%);
background: -webkit-gradient(linear, left top, left bottom, color-stop(0%,#00b7ea),
color-stop(100%,#009ec3));
background: -webkit-linear-gradient(top, #00b7ea 0%,#009ec3 100%);
background: -o-linear-gradient(top, #00b7ea 0%,#009ec3 100%);
background: -ms-linear-gradient(top, #00b7ea 0%,#009ec3 100%);
background: linear-gradient(to bottom, #00b7ea 0%,#009ec3 100%);
filter: progid:DXImageTransform.Microsoft.gradient( startColorstr='#00b7ea',
endColorstr='#009ec3',GradientType=0 );
color: #fff;
}
.my-footer {
background: #eee;
margin-bottom: 10px;
padding: 10px;
margin-bottom: 25px;
font-size: 12px;
font-weight: bold;
text-align: center;
padding: 15px;
border-radius: 5px;
color: #fff;
background: #45484d; /* Old browsers */
background: -moz-linear-gradient(top, #45484d 0%, #000000 100%); /* FF3.6+ */
background: -webkit-gradient(linear, left top, left bottom, color-stop(0%,#45484d),
color-stop(100%,#000000)); /* Chrome,Safari4+ */
background: -webkit-linear-gradient(top, #45484d 0%,#000000 100%); /*
Chrome10+,Safari5.1+ */
background: -o-linear-gradient(top, #45484d 0%,#000000 100%); /* Opera 11.10+ */
background: -ms-linear-gradient(top, #45484d 0%,#000000 100%); /* IE10+ */
background: linear-gradient(to bottom, #45484d 0%,#000000 100%); /* W3C */
filter: progid:DXImageTransform.Microsoft.gradient( startColorstr='#45484d',
396 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Pages, the page editor, and grid controls
endColorstr='#000000',GradientType=0 ); /* IE6-9 */
}
</style>
<div class="my-header">
<img src='{!#HOSTED_FILE.53382#url}' border='0' align='absleft'/>
Great Reads Check Out System
</div>
The following, in the HTML Footer section, defines the footer:
<div class="my-footer">
May your days always have happy endings!
</div>
Customizing application tabs and menus
Tabs and their child menus provide navigation through Rollbase application pages.
See Application tabs and menus on page 91 for a conceptual overview of application tabs and menus.
You can change a tab to be a child menu by adding a parent tab to it. See Changing a tab to be a child menu
on page 397 for details.
You can promote a child menu to be a tab by removing its parent tab. See Promoting a child menu to a tab on
page 397 for details.
You can customize the icons used for tabs and menus when using the Modern - Vertical Menus UI blueprint.
See Customizing icons for the Modern -Vertical Menus UI blueprint on page 398
Changing a tab to be a child menu
You can change a tab to be a child menu by adding a parent tab to it. It will appear in an application page as
a submenu to a tab.
To change a tab to a menu:
1. Navigate to an application setup page that uses the tab you want to change:
• To navigate to settings for the current application, click App Settings from the application switcher.
• To navigate to settings for a different application, hover your mouse pointer over the application in the
application switcher and click the settings icon.
2. Click Tabs in the ribbon.
3. From the Tabs table, click Edit in the row for the tab you want to modify.
A page opens that allows you to edit tab properties.
4. From the Parent Tab drop-down menu, select the tab on which you want this tab to appear as a menu.
5. Click Save.
Promoting a child menu to a tab
If a top-level tab has been changed to a child menu of another tab, follow these steps to make it a top-level
tab again:
1. Navigate to an application setup page that uses the tab you want to change:
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 397
Chapter 7: Customizing the user experience
• To navigate to settings for the current application, click App Settings from the application switcher.
Note: The Application Switcher is available as a drop-down menu next to the application name
irrespective of the UI Blueprint selected.
• To navigate to settings for a different application, hover your mouse pointer over the application in the
application switcher and click its associated Application Settings icon.
2. Click Tabs in the ribbon. To edit a child menu, you must edit its parent tab.
3. From the Tabs table, click Edit in the row for the parent tab.
A page opens that allows you to edit tab properties.
4. In the Menus table, click Edit in the row for the child menu you want to promote:
5. From the Parent Tab drop-down menu, select None (top level tab).
6. Click Save.
Customizing icons for the Modern -Vertical Menus UI blueprint
If your application is configured to use the Modern - Vertical Menus UI blueprint, Rollbaserenders the icons
in the sidebar with the first letter of the name of the tab by default. If the sidebar is collapsed, the name of the
tab is displayed when you hover the mouse over the icon.
You can customize the tab icons in the following ways:
• Configure them to display two letters instead of one. For tabs with one word in their names, the icon contains
the first two letters of the name. For tabs with more than one word in their names, the icon contains the first
letter of the first two words.
• Configure an individual tab to use a font icon. You can select a font icon from Bootstrap Glyphicons or Font
Awesome icons. Progress recommend Font Awesome icons, which are SVG icons that work well with
resizing for different font size and work well with different themes.
• Configure an individual tab to use a custom image as its icon.
To configure tab icons to display two letters, set the value of the property
rb.newui.options.numOfCharsInTabDefaultIcon to 2. You must set the value of this property in a
custom sidebar script that executes before the UI starts, for example:
<script id="executeBeforeUIStarts">
rb.newui.options.numOfCharsInTabDefaultIcon=2;
</script>
The following screen shows the resulting icons in a collapsed sidebar:
398 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Pages, the page editor, and grid controls
To configure an individual tab to use a font icon:
1. Edit the tab whose icon you want to change.
2. Select Font icon as the Icon Type, select the Font classes, and select the icon from the set of available
icons. You can also search for icons by name.
The following screen shows an expanded sidebar where the Devices tab uses a font icon:
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 399
Chapter 7: Customizing the user experience
To configure an individual tab to use a custom image as its icon:
1. Edit the tab whose icon you want to change.
2. Select Custom as the Icon Type and select the file to use as the menu icon:
The following screen shows a collapsed sidebar where the Devices tab uses a custom icon:
400 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
UI Blueprints
UI Blueprints
UI blueprints allow you to set how the application renders in the New UI. This is called the UI blueprint for the
application. At a high level, a UI blueprint is how the application navigation and various menus inside the
application are rendered. The page content does not change across blueprints.
The Traditional blueprint has a Rollbase menu (collapsed by default), a header, which includes the application
switcher and the application tabs and menus, and a footer:
The Modern - Vertical Menus blueprint, which is the default for new applications, has a sidebar that includes
the application tabs and menus drawn vertically, a header that includes the application switcher, and no footer.
The sidebar has two states: Expanded and collapsed (see screens below). This blueprint is adaptive; it renders
differently based on the device.
It is the default blueprint when an administrator creates a new application.
• On mobile devices, if tabs (menus) overflow the screen, users can drag the strip to navigate to to all tabs.
• On mobile devices, page tab names are now rendered in uppercase characters on View pages.
• On mobile devices, you can navigate to the previous and next records from a View page using a swipe
action. A left swipe will navigate to the next record and right swipe will navigate to the previous record.
• The application setting, Use Native Calendar and Time Control, renders date and time controls as native
widgets on mobile devices
The following screen shows the Modern - Vertical Menus blueprint on a desktop with the application switcher
selected.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 401
Chapter 7: Customizing the user experience
The following screen shows the Modern - Vertical Menus blueprint with Field Label Render Modefor
Smartphone.
You can customize the tab icons for the Modern - Vertical Menus UI blueprint. See Custom icons for tabs in
Modern - Vertical Menus blueprint for more information.
To set the UI blueprint for an application:
1. Navigate to the Setup Application page for the application.
2. Click Edit.
3. In the New UI Specific Settings area, choose the needed UI blueprint - either Traditional or Modern -
Vertical Menus based on the device such as UI Blueprint for Desktop or UI Blueprint for Mobile
(smartphone, tablet portrait or tablet landscape) .
4. Click Save.
You can also set the UI blueprint for an application using App Preview on page 405.
The UI blueprint for each application appears in the application list on the Applications Setup page:
402 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Setting a Different UI Blueprint on Mobile Devices
Setting a Different UI Blueprint on Mobile Devices
Rollbase provides an option to set different blueprint for mobile devices. You can specify one blueprint each
for both desktop and mobile devices. If the blueprint for mobile devices is not set, the desktop blueprint will be
used to render the UI.
UI Blueprint type as seen in the App Preview:
On desktop devices:
On mobile devices:
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 403
Chapter 7: Customizing the user experience
Both the UI Blueprint Desktop and UI Blueprint Mobile can be seen on the application setup page as well.
1. Browse to Application Setup and click Edit > New UI Specific Settings
2. From the UI Blueprint Desktop drop-down, select Traditional as the UI blueprint.
3. From the UI Blueprint Mobile drop-down, select Modern-Vertical Menus as the UI blueprint.
4. To view the UI Blueprint during the App Preview session, do any one of the following, as needed.
• Select the Desktop icon to view the desktop UI blueprint "Traditional".
• Select the Mobile (smartphone or tablet) icon to view the mobile UI blueprint "Modern-Vertical Menus".
404 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
App Preview
App Preview
App Preview is a tool where, an administrator can preview changes to various aspects of an application on
the fly without disturbing any users. The full live application is available to change and review. This helps to
improve your productivity when designing the application's user interface.
Open App Preview from the Rollbase application swicther.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 405
Chapter 7: Customizing the user experience
The App Preview menu option lets you select the following:
• Change the Text direction based on the language. See Language support on page 740 for more information
about language support and text direction.
• The theme for the application. See Working with themes on page 455 for more information about themes.
• Select preferred Notifications Position.
• The type of device to preview: smart phone, tablet in portrait mode, tablet in landscape mode, or desktop.
• The UI blueprint for the application. See UI Blueprints on page 401 for more information.
• The field label setting to choose a preferred way of rendering the field labels based on the selected device.
See Customizing field labels on page 430 for more information about field label settings.
• The card templates used to display record lists on different mobile devices. See Cards and card containers
on page 411 for more information about cards.
Use the checkmark icon to save your changes and click Save Applications Settings? > Ok dialog to save.
The changes are applied and the App Preview window is closed.
Use the X mark icon to discard changes and exit from the App Preview.
406 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
App Preview
The following screen shows the App Preview interface. In this example, the user has selected the smart phone
interface, selected a different theme, and selected a user-defined card:
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 407
Chapter 7: Customizing the user experience
When viewing a record list page on a mobile device, it is rendered using a card container by default (see Cards
and card containers). To switch the view to the normal record list view, click the Switch to Grid button:
To switch back to the card container, click the Switch to Card button:
Adaptive user interface
Rollbase applications are adaptive; you can tailor user interface components in the same application to appear
differently on different devices. Rollbase also automatically applies some adaptive features. See Automatic
adaptive features for different devices on page 409.
408 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Adaptive user interface
Adaptive features include:
• Rollbase renders record list pages on mobile devices using cards and card containers. See Cards and card
containers on page 411 for information about cards and card containers. See Creating and editing cards on
page 413 for details about creating and editing cards.
• Tabs, page sections, views, and buttons are tailored to the device(s) on which they will be visible. See
Tailoring page components and views to devices on page 428 for more information.
• You can position field labels above field values on specified devices. You can also hide individual field
labels. See Customizing field labels on page 430 for more information.
• Rollbase includes client-side JavaScript functions for detecting mobile devices. See Functions on page 1140
for details.
• Rollbase includes CSS classes for detecting mobile devices. See Custom CSS on page 507 for details.
Automatic adaptive features for different devices
By default, Rollbase renders application pages differently on desktop and mobile devices.
Only deployed applications are available on mobile devices; setup pages are not included. Automatic
modifications to the user interface on tablets and smart phones, detailed below, are designed to provide a
better user experience on each type of device.
The UI on both tablets and smart phones includes the following:
• The default font size on a mobile device is the desktop font size plus 2 (14pt by default).
• The Rollbase menu:
• Is rendered in non-administrative mode.
• Includes a Log Out menu item
• Log Out and Rollbase Forum are under the userName menu item in the Modern - Vertical Menus
UI blueprint.
• Does not include the Subscription Details menu item.
The following screen shows the Rollbase menu in the Traditional UI blueprint on a smart phone:
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 409
Chapter 7: Customizing the user experience
The following screen shows the Rollbase menu (also called the sidebar) items and application tabs, in the
Modern - Vertical Menus UI blueprint on a smart phone:
• The application switcher is rendered in non-administrative mode.
The following screen shows the application switcher in the Traditional UI blueprint on a tablet:
• The branding header and footer are not displayed.
410 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Adaptive user interface
• The user profile menu is not displayed.
• On View pages, there is no more actions menu and the only available action is Delete.
• On record list pages:
• The list of records is rendered as cards in a card container by default. See Cards and card containers
on page 411 for more information. You can toggle between card mode and grid mode.
• When displaying in grid mode, you can sort columns (short press on column header) and change
column order by pressing longer and dragging a column to the desired location.
• The view selector does not contain any administrative actions (cannot edit, color code, or clone a view).
• The view selector is not displayed if there is only one view available.
• Global search is rendered in non-administrative mode.
• The page menu only contains the new record menu item when using the Traditional UI blueprint. When
using the Modern - Vertical Menus UI blueprint, there is no page menu.
• The page options menu is not displayed.
• Inline editing is disabled.
• Only the refresh action is available for charts and gauges.
• There is no user profile menu.
The UI on tablets includes the following:
• Report links only contain Email this Report.
The UI on smart phones includes the following:
• The Rollbase menu does not have the Recycle Bin or Recent Items menu items.
• When displaying a record list page in grid mode:
• Buttons on the page toolbar have no text.
• The list component has no Actions column.
• On record list pages, the view selector has no label.
• There is no quick create button on record list pages. You can still create records using the New page.
• Report links do not have any actions. The only option is to run the report.
Cards and card containers
Rollbase uses cards and card containers to render record list views on mobile devices. A card is analogous to
a row in a record list view. A card container is analogous to the grid that holds the row. There are two types of
card containers:
• Vertical — A vertical, scrollable list of cards. Each card consumes the width of the screen. You can use
vertical card containers on smart phones and tablets.
• Horizontal — A scrollable grid of cards. Each card is has fixed dimensions; you can configure the dimensions
in the card editor. You can use horizontal card containers on tablets and desktops.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 411
Chapter 7: Customizing the user experience
The card editor and wizard now allows you to design vertical and horizontal card containers. You can select
which container Rollbase will apply depending on whether the user is accessing the application with a mobile
phone, a tablet (in horizontal or vertical orientation), or a desktop.
The differences between horizontal and vertical card containers include:
• You can only use horizontal card containers for desktop and tablet devices.
• Horizontal cards have a fixed width (cards for vertical container use the whole width of the device).
• A horizontal container can render multiple cards on the same line.
• A horizontal card container supports paging, but not infinite scrolling.
• To perform actions in the group actions menu, you can select a card by clicking it and you can select multiple
cards using the control key.
By default, a vertical card container will render with the default card. It displays the record name and a way to
drill down to individual records:
412 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Adaptive user interface
There is no default horizontal card.
You can change the view to the regular record list view (grid) by clicking the icon at the top right, and you can
toggle the view back to the card container view. You can create your own cards from a selection of existing
designs and layouts or from scratch. See Creating and editing cards on page 413 for details.
Creating and editing cards
The card editor allows you to create and edit cards for displaying in card containers on various devices.
The card editor includes the following features:
• You can resize coumns in the editor pane.
• You can drag and drop labels and values from sidebar/
The card editor toolbar includes the following:
• More text formatting tools
• Insert Horizontal Line
• Undo/Redo
• Select All
• Code View - Opens the card in an HTML editor view.
• Insert Link
• Insert Image
• Insert Video
• Upload File
• Insert Table
• RTL and LTE text direction - Allows you to change the card's text direction for an individual field. The card's
text direction is determined by the user's language.
• Add Card Dimension, allows you to set the dimensions of a card to be displayed in a horizontal card
container. This tool is not available when editing a card to be displayed in a vertical card container. You can
set the card width for desktop and tablet devices, the card height, and CSS styles to apply to the card
container.
• Add Text Limit, allows you to limit the amount of text displayed for text fields. You can limit the text by
specifying a line count or by specifying a character limit
Creating a card
There are four ways to create a card:
• Start with an existing card design — Allows you to create a card quickly and easily by selecting fields to
display in pre-designed components
• Start with an existing card layout — Allows you to choose a column layout for the card and select fields to
display in each column
• Start with a blank screen — Allows you to design your own card layout and select fields to display.
• Start with any of the above options and edit the resulting HTML in any HTML editor.
To create a new card:
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 413
Chapter 7: Customizing the user experience
1. Decide the object type for which you want to create a card and open a record list page for that object type.
2. Open App Preview and select a device.
3. Click + Create a New Card:
4. Select a Card Container Type:
• Vertical container — Displays cards vertically; each card consumes the width of the screen. This option
is supported on smart phones and tablets.
• Horizontal container — Displays cards in a grid; each card is has fixed dimensions; you can configure
the dimensions in the card editor. This option is supported on tablets and desktops.
414 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Adaptive user interface
5. Select a pattern for the card. You can select an existing design in the Design tab or you can select an
existing layout or a blank card canvas from the Layout tab. The following screens show vertical card designs
with an example on a smart phone and horizontal card designs with an example on a tablet.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 415
Chapter 7: Customizing the user experience
6. Select the device(s) for which you want to create the card. Depending on the card container type, you can
select smart phone, tablet in portrait mode, or tablet in landscape mode.
7. If you selected a design, click Next and map components in the card to fields as described in Mapping
components to fields on page 417. If you selected a layout, or after mapping components to fields, click +
Create a New Card and edit the card in the card editor as described in Editing a card in the card editor on
page 418
8. Type a name for the card in the Card Name field and click Save to save the card.
Editing a card
To edit an existing card, click the edit icon next to the card:
The card editor(add link) opens for the card.
416 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Adaptive user interface
Card options in the page editor
A view component (list view) now includes card-related properties you can set in the page editor:
The properties Select Desktop Card, Select Tablet Card, and Select Smart Phone Card let you select the
card to user for tablets and smart phones. Click Create to create a new card. Click Edit to edit the selected
card.
See the following topics for details about mapping components to fields and using the card editor:
• Mapping components to fields on page 417
• Editing a card in the card editor on page 418
Mapping components to fields
When you start a card from a design, you need to map the components in the card to fields in the object. The
Image Left design, selected in the screen below, contains components for an image and a star rating, which
renders stars for a numeric field. You can edit the star rating by changing the color, size, and icon used; see
Editing a card in the card editor on page 418
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 417
Chapter 7: Customizing the user experience
In this example, Rollbase automatically populated the image component with the Photo field from a Room
object because it is the only Image field in the object definition. If there were multiple Image fields in the object
definition, you could choose from among those fields in the drop-down list. Rollbase also automatically populated
the rating component with the Rating field. Again, if there were multiple Integer or Decimal fields in the object,
you would be able to select any of them from the drop-down list. For each component, either select a field or
select Ignore field.
When you are finished mapping fields, click + Create a New Card. The card opens in the card editor. You can
either save the card or you can continue to edit the card as described in Editing a card in the card editor on
page 418
Editing a card in the card editor
When you start a card from a layout or from a blank screen, or after you have mapped the fields in the card,
the card editor opens. The card editor is an HTML editor that includes Card Tools for adding components and
other features to the card. In the card editor, you have the full power of HTML, CSS, and JavaScript hash
templates at your disposal to create very good looking and very powerful cards.
The card editor toolbar contains buttons for formatting and aligning text, editing HTML, inserting images, videos,
files, and tables, and for setting the text direction (LTR or RTL) for a field in the card (Text direction for the card
is based on the user's language; you can override the direction for a field).
From the Values and Labels areas in the sidebar, you can drag values and fields onto the card.
The Use this card for buttons let you select the devices for which to use this card.
418 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Adaptive user interface
The screen below shows the card editor for a new card created from the 2 Column layout. When you create
a card with this layout, the card is pre-populated with an Object Name Label, an Object Name value, and an
object view link that drills down to the View page for a record. You keep, edit, or delete these as desired.
The card editor includes several card tools, available from the Card Tools area in the sidebar:
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 419
Chapter 7: Customizing the user experience
Card Tools include:
• Add Object View Link — Places an object view link on the card. An object view link drills down to the View
page for a record.
• Add Rating — Lets you add a star rating component to the card. A star rating component can represent
an Integer, Decimal, Currency, or Percentage field with a range of values between 1 and 10, or a Formula
or Expression field that returns an Integer or Decimal value between 1 and 10. You can select an icon for
the component (defaults to a star), an icon color, and apply CSS styles to the star rating. Preview Rating
shows you what the resulting component will look like. If you select the default icon or a Font Awesome star
icon, Decimal values will render half stars if the decimal part of the value is greater than or equal to 0.5.
• Add Percentage Bar — Lets you add a percentage bar to the card. A percentage bar can represent an
Integer, Decimal, Currency, or Percentage field with a range of values between 0 and 100, or a Formula or
Expression field that returns an Integer or Decimal value between 0 and 100. You can select colors for the
bar, apply CSS styles to the bar container, and specify whether to display the percentage value and where
to display it. Preview Percentage Bar shows you what the resulting component will look like.
420 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Adaptive user interface
• Add Color Side Bar — Lets you add a conditional color side bar to the card based on a Boolean value. A
color side bar can represent a Formula or Expression field with a Boolean return type or a Checkbox field.
You can choose the color for the bar when value is true or false and you can choose the bar size. Preview
Color Side Bar shows you what the resulting component will look like.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 421
Chapter 7: Customizing the user experience
• Add Card Dimension — Lets you set the dimensions of a card to be displayed in a horizontal card container.
This tool is not available when editing a card to be displayed in a vertical card container. You can set the
card width for desktop and tablet devices, the card height, and CSS styles to apply to the card container.
The screen below shows the Add Card Dimension dialog:
422 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Adaptive user interface
• Add Text Limit —Lets you limit the amount of text displayed for text fields. You can limit the text by specifying
a line count or by specifying a character limit. The screen below shows the Add Text Limit dialog:
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 423
Chapter 7: Customizing the user experience
At any time while editing a card, you can click the Code View button to view and edit the HTML source:
The HTML source opens:
You can edit the HTML source in the card editor or you can copy the HTML source and edit it in a different
HTML editor.
424 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Adaptive user interface
When you insert a field using the card editor, Rollbase generates the following HTML fragment (value or label):
<span data-column-id=”fieldId” data-column-type=”value”>
<span data-column-id=”fieldId” data-column-type=”label”></span>
For example, the following HTML fragment was generated for a label and value for a City field. Note that the
data-column-id attribute uses the integration name of the City field, which is city.
<span class="rbs-dataColumn-label" data-column-id="city"
data-column-type="label" title="label - city">City</span>
<span class="rbs-dataColumn-value" data-column-id="city"
data-column-type="value" title="value - city">Austin</span>
You can use the span element to simulate what the card editor does, especially if you want to work in your
own HTML editor.
Note: If you are planning to work in your own HTML editor, you can obtain the integration names for the fields
you want to use by creating a card from a blank canvas, adding a field label or value for each field to the card,
and viewing the HTML source. The source will contain the integration name of each field in the data-column-id
attribute. Copy the source and paste it into your HTML editor to keep the integration names available.
The new card tools support the following:
• Add/Edit Card Script — Lets you customize a card by executing scripts.
• Script that you add in the first box runs as soon as data is fetched from the server and before rendering
the cards. It takes three arguments:
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 425
Chapter 7: Customizing the user experience
• cardData — An array of the values used to render the card
• dataSource — The Kendo Datasource used by the card
• cardListview — The KendoListView (KendoMobileListView for mobile devices ) component
that renders card items
The following example prepends Custom_ to the name of each title record:
var someData = "Custom_" + cardData["name"];
cardData["name"] = someData;
The following screen shows the resulting cards on a tablet:
• Script that you enter in the second box runs once after rendering all cards on the page. It takes three
arguments:
• cards — A list of all cards on the page
• dataSource — The Kendo Datasource used by the card
• cardListview — The KendoListView (KendoMobileListView for mobile devices ) component
that renders card items
426 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Adaptive user interface
The following example adds a kendoSlider component to each card on the page:
if(cards){
//Iterate through all card list item
for(var i=0;i<cards.length;i++){
var card = $(cards[i]);
//Find an element where we want to render kendo slider
var tempSliderEle = card.find('.temperature');
tempSliderEle.show();
var tempSlider = tempSliderEle.data('kendoSlider');
var recUid = card.attr('data-uid');
if(recUid){
var rec = dataSource.getByUid(recUid);
var recId = rec["recordId"];
var currTempVal = rec["Set_Temperature"];
var confirmMsgEle = card.find('.confirmTempChange');
if(!tempSlider){
tempSliderEle.kendoSlider({
max:100,
min:0,
value:currTempVal,
dragHandleTitle:'Drag to change temparature',
tickPlacement:'bottomRight',
recId:recId,
currTempVal:currTempVal,
});
}
}
}
}
The following screen shows the resulting cards on the page:
• Add/Edit Card Style — Lets you add custom CSS styles. By default, the styles apply to all sections on a
page. This typically works just fine. But if a page contains multiple list views, and you want different styles
for each, you can make the style specific to the page section that contains the list. To apply a style to a
specific section, use the section original ID prefixed by #rbi_S_ . You can find the section ID by opening the
page in the page designer and selecting the section. For example, to identify a section with the original ID
of ZR_XI0e5TUO5BQIVgzgeIA, use:
#rbi_S_ZR_XI0e5TUO5BQIVgzgeIA
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 427
Chapter 7: Customizing the user experience
Tailoring page components and views to devices
You can tailor tabs, page sections, views, and buttons to specify the devices on which they will be visible.
Each of these components has a property, Show In, which lets you select the devices on which you want them
to appear.
The following screen shows this property for a tab. You can select or deselect desktop, tablet, and smart phone.
The list of tabs for an application shows the settings for this property in the Show In column:
428 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Adaptive user interface
You can specify on which devices a page section is visible by editing the Show In property for that section in
the page editor:
When creating or editing a view, you can select the devices on which a view is available by selecting devices
in the Show In property:
The table of views for an object definition has a Show In column that displays the devices selected for each
view.
When you create or edit a button for an object, you can select the devices on which it will be visible in the Show
In property:
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 429
Chapter 7: Customizing the user experience
The Show In property is displayed in the table of buttons in the object definition. See Using buttons on pages
on page 393 for more information about buttons.
Customizing field labels
You can configure, at the application level, that labels are rendered above field values on certain devices. You
do this by selecting a value for the Field Labels Render Mode property for an application. The default selected
value is Show labels above value field only on Mobile. The following screen shows the Field Labels Render
Mode drop-down menu on the Setup Application page:
You can also hide individual field labels on View pages. This is useful for instances where the label is redundant,
for example, an image field.
430 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Responsive user interface
To remove a field label from the UI, open the View page in the page editor and select the Remove Label
property for the field.
Note: For field types such as a checkbox, formulas, templates, image upload and integration link, the Hide
Label checkbox exists while creating the field but is unchecked by default. In case, both Hide Label and
Remove Label are enabled, the Remove Label functionality takes precedence.
Responsive user interface
Many Rollbase components use responsive user interface design. This means they adapt to a variety of screen
widths, either by resizing (such as images) or by reorganizing (such as in a View or Edit page with multiple
columns). Responsive components improve the user experience on applications that are viewed on a variety
of devices.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 431
Chapter 7: Customizing the user experience
Responsive features include:
• Responsive application menu bar with overflow. If the screen width is too narrow to display all tabs, the
rightmost tab(s) move into an overflow menu:
• Vertical and horizontal responsive design modes for pages with multiple columns (except Record List pages).
These modes define how multiple columns are displayed on different screen widths. Vertical responsive
design is the default. See Vertical and horizontal responsive design on page 433 for details.
• Responsive dashboard pages. See Responsive dashboard pages on page 436 for details.
• Responsive page title and toolbar. See Responsive page title and toolbar on page 435 for details.
• Responsive images
Image fields are responsive by default. You can control responsiveness and maximum size for an image
by setting properties in the page editor for the image field. If the Responsive property is selected (the
default), you can set the Max Width property to control the maximum width of the image. The Responsive
property only affects desktop devices; images on mobile devices are always responsive. To make an image
non-responsive, deselect the Responsive property.
432 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Responsive user interface
• Responsive image carousels
To control the carousel's space consumption, you can specify a maximum width for the carousel in the page
editor by setting the Max Width property (in pixels) for the first image field. A carousel is responsive to the
cell in which it is rendered on the page, keeping the proportions of the image. It is responsive even if the
images are not responsive. For more information about image carousels, see Image Upload field on page
1312.
• Responsive charts
Charts are responsive and are auto-scaled to fit the available space. Auto-scaling is done only if the available
space is less than the configured chart dimensions. Otherwise, the chart will always be rendered with the
configured dimensions. To enable responsive charts, the chart property Fit to Container Size must be
selected (selected by default). See Creating charts on page 343 for more information.
Vertical and horizontal responsive design
Rollbase supports vertical responsive design as the default responsive mode. You can still select horizontal
responsive design at the application level. See Editing applications on page 109 for details.
Responsive design is geared towards providing optimal viewing of apps on a variety of devices. For a Rollbase
application, you can design pages such as View, New, and Edit pages with multiple columns. Those columns
are displayed differently on different device sizes. Vertical responsive design will cause columns to display
differently from horizontal responsive design on smaller devices.
Note: Progress recommends using one, two, or four columns on View, New, and Edit pages.
For example, if a page contains four columns, the columns display as shown below on a large device:
Using vertical responsive design on a medium device, the columns display as shown below:
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 433
Chapter 7: Customizing the user experience
Using vertical responsive design on a small device, the columns display as shown below:
Using horizontal responsive design, the columns display as shown below on a large device:
Using horizontal responsive design on a medium device, the columns display as shown below:
Using horizontal responsive design on a small device, the columns display as shown below:
When using vertical responsive design, the recommended setting for Navigation Order (a page property) is
Top to bottom, then left to right. Otherwise tab navigation through fields will not behave as the user expects
on smaller screens. For horizontal responsive design, the recommended setting for Navigation Order is Left
to right, then top to bottom to achieve the expected behavior.
434 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Responsive user interface
To set the navigation order:
1. Navigate to the object definition that includes the page for which you want to set the navigation order.
2. Navigate to the Pages section.
3. Click Properties on the page row.
4. Select the desired Navigation Order:
Responsive page title and toolbar
On View and Edit pages, the page title and toolbar are responsive. The page title area has two parts:
• The page title
• The page toolbar.
By default, the available page width is shared as follows:
• On medium and large devices (width is 769px or greater), the width is shared equally by both parts.
• On small devices (width is 768px or less), the page title consumes 30% of the width and the toolbar consumes
70% of the width.
Administrators can override these proportions at the application level to change the percentage of space
occupied by the page title to give the toolbar more space to display actions in the toolbar rather that in its
overflow using the following CSS classes:
• .rbs-objectViewTitle — CSS class to customize the width of the page title in a record view page
• .rbs-objectEditTitle — CSS class to customize the width of the page title in a record edit page
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 435
Chapter 7: Customizing the user experience
To customize the width of the page title for an application, add custom styles to either the custom header or
to the custom sidebar. The following example changes the width of the page title to consume 20% of the screen
width on view pages:
<style>
@media only screen and (min-width: 769px) {
/* Device is Small, medium, large */
.rbs-objectViewTitle,.rbs-objectViewTitle {
width: 20%; /* Rest of space will be consumed by toolbar buttons and overflow */
}
}
@media only screen and (max-width: 768px) {
/*Device is Extra Small */
.rbs-objectViewTitle,.rbs-objectViewTitle {
width: 20%; /* Rest of space will be consumed by toolbar buttons and overflow */
}
}
</style>
For information about adding code to custom headers and sidebars, see Header and footer on page 117 and
Custom sidebar on page 117.
Responsive dashboard pages
Rollbase supports responsive generic pages (pages you create from generic tabs; see Creating tabs and pages
on page 362) with a fallback mechanism to revert to the way the Classic UI and the New UI (up to version 4.1)
rendered them (fluid). Customers frequently use generic pages as dashboards. This feature applies to generic
pages with two columns and works in the following way:
• On desktops and on tablets in landscape mode, the page will display two columns.
• On tablets in portrait mode and on smart phones, the page will display one column.
The responsive mode is on by default. If you want to go back to Fluid rendering (HTML table rendering) for
dashboards to be compatible with the way they were in the Classic UI, you can set the Render Mode property
on the page in the page editor. This property is only available if the page has two columns.
The screen below shows where to set the Render Mode property in the page editor.
436 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Working with views
Working with views
Views are result sets. They are key object components because they determine how a user finds records and
navigates through them. This section discusses how to create and configure views, and how to define grouping,
sorting, totaling, and filtering behaviors (including dynamic filtering, expressions, and exporting).
To troubleshoot views on Rollbase Private Cloud, an administrator on the master tenant can enable logging
of SQL queries and results. For more information, see Enabling logging for charts and views on page 829
Creating and editing views
As an administrator, you can create and edit views to return specific records. Follow these steps to create or
edit a view:
1. Navigate to the object definition for the type of records you want to display in the view. For example, select
Object Definition from the page menu.
2. From the ribbon listing object components, click Views.
3. Do one of the following:
• To create a view, click New View. The New View page opens.
• To edit a view, click Edit next to the view. The Edit View page opens.
The View Name section contains the following:
4. Enter a name and choose from the following options:
• Hide this View from View Selector — When selected, this view is not available in the view selector on
application pages.
• Hide count of total records for this View — When selected, users will see better performance for
complex views with many records.
• Private — When selected, this view cannot be published as part of an application or be used in other
components such as triggers and templates.
• Show In — The types of devices in which this view is available (desktop, tablet, smart phone). The
following rules apply:
• By default, existing views are available on desktops and tablets but not on smart phones. To enable
a view on smart phones, you must manually enable it.
• If there are no views available on tablets or smart phones, Rollbase uses the default view for rendering
data (at least one view is mandatory). By default, the default view is enabled for all devices and the
setting is disabled for editing.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 437
Chapter 7: Customizing the user experience
5. In the Columns section, select the fields to display as columns.
6. In the Sorting and Grouping section, optionally select whether to sort and/or group records in the view.
See Sorting and grouping on page 439 for more information.
7. In the Totals and Subtotals section, optionally define columns for which you want to calculate totals. See
Calculating values for columns on page 441 for more information.
8. In the View Filters section, choose the fields and operation for filtering. See Filtering views on page 442 for
more information.
9. In the Permissions section, specify which roles and users can see this view. See Role-based access control
on page 648 for more information.
10. Click Save.
You can also edit a view on an application page. See Editing a view on an application page on page 448 for
details.
Adding columns
When you create a new view, the record name field is automatically added to Selected Columns. If you do
not include the record name field in the view, Rollbase displays a warning message asking if you are sure you
do not want to include it. The record name field provides a link to drill down to the record's detail page, which
is why it is typically not a good idea to exclude this field from your views.
You can include templates and formula fields in a view. However, this might result into decreased performance
due to a high volume of server-side calculations.
You can define which fields you want appear as columns in your view. For example, you might want to hide
this column in views exposed in external portals. See Field actions on page 138 for more information.
Move the columns you want in the view to the Selected Columns list. Use the arrows on the right to change
their position in the view:
438 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Working with views
Use the checkbox labeled Show "Actions" column in this view to specify whether or not you want users
who can access this view to see the standard Actions column that contains edit and delete controls:
Sorting and grouping
You can sort and group a view by column values. For example, the following view groups title records by author,
and sorts each group alphabetically:
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 439
Chapter 7: Customizing the user experience
The Sorting and Grouping section of the Edit View page allows you to specify sorting and grouping:
This section has the following options:
• Group By — Select a field from the first drop-down list if you want records grouped by that field. Select
Ascending or Descending from the second drop-down list to specify the order in which grouped records
will appear.
• Sort By — Select a field in the first drop-down list to sort records by that field. Select Ascending or
Descending from the second drop-down list to specify the direction in which records will appear.
• ...then by — Select a column and direction to further sort records in the view.
• Disable dynamic records sorting by clicking on the links atop of columns. — Select this check box
to disable dynamic sorting in a view. See Column data options on page 455 for more information.
440 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Working with views
In the following screen, the view groups Title records by Author; within each group, the records are sorted by
Title and then by Status.
Calculating values for columns
You can configure a view to provide mathematic functions for numeric columns or provide a count for non-numeric
columns. You can provide totals for up to three separate columns.
For numeric fields, you can select the following options:
• Total - the sum of all non-null values
• Average - the total divided by number of records with non-null values
• Count - the number of records (also available for non-numeric fields)
• Min - the minimum of all non-null values
• Max - the maximum of all non-null values
• Variance - the statistical variance of all non-null values
• Standard Deviation - the square root of Variance
When totaling is enabled for one or more columns, two extra rows become available at the bottom of the view
displaying the following:
• The calculated subtotal for the set of records shown on the current group (if grouping is enabled). If the
current group spans multiple pages, the subtotal is calculated for all pages.
• The calculated amount for the set of records shown on the current page.
• The sum of amounts for all records in this view on all pages (grand total). This is not available for formula
fields.
You can turn off any of these three ways of totaling for the view you are editing.
Note the following limitations:
• Due to performance considerations, a grand total cannot include formula fields. Totaling by formula fields
is only available for subtotals and page totals.
• The grand total does not display for Average, Min, Max, Variance and St. Deviation when you combine
Event or Task fields with other fields.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 441
Chapter 7: Customizing the user experience
In the following screen, Furniture record columns are totaled by Total for Quantity:
The resulting view looks like the following:
Filtering views
You can filter a view to display records that meet certain criteria.
442 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Working with views
See the following topics for details:
• #unique_430
• Filter criteria on page 443
• #unique_431
• Filtering OpenEdge Service objects by search criteria on page 446
Filtering by date intervals
You can filter records used in views by dates. A date filter is applied before any other filter(s) you create.
From the first drop-down menu, select the Date or Date/Time field. From the second drop-down menu, select
the interval relative to the current date, for example, Current Year, Previous Quarter, Last Month, This Week,
or Last 30 Days.
The following shows a partial list of available date intervals:
Filter criteria
When defining a view, you can add detailed filter criteria to narrow the result set. This filtering mechanism is
the same that Rollbase uses for object-specific searches and for reports to determine which records are shown
in the output.
The filter mechanism allows you to add up to five filters by selecting a field, an operator, and a value. You can
additionally filter by a date interval.
For example, in the filter criteria shown below, the filter specifies records (in this case, library book titles) where
the title's Status field equals Available.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 443
Chapter 7: Customizing the user experience
The operators available depend on the selected field type. The operators are: equals, not equal to, less
than, greater than, less or equal, greater or equal, starts with, contains, does not
contain, is one of, is not one of, is empty, and is not empty.
The Filter Conditions parameter allows you to control how each of the filters is used to determine the output
of the view:
• All (AND): Selecting this condition means that all filter conditions must be met in order for a record to display
in this view.
• Any (OR): Selecting this condition means that at least one of the filter conditions must be met in order for
a record to display in this view, but it doesn't matter which one.
• Expression: Expressions allow you to specify how filters should be evaluated together to determine whether
or not a record should be shown in the view. To define an expression, use the numerical value of the filters
(1 through 5) along with AND, OR, and NOT keywords and parentheses "(" ")" to group subexpressions
together. For example:
• (1 OR 2) AND 3 - Only show records that match filter 3 and at least one of 1 or 2
• (1 AND 2) OR NOT 3 - Only show records that either match both 1 and 2, or do not match 3.
• (1 AND 2) OR (3 AND 4) - Only show records that match both 1 and 2, or both 3 and 4.
• (1 AND (2 OR 3)) OR NOT 4 - Only show records that do not match 4 or those that match 1 and
either 2 or 3.
• Formula: The Formula filter condition allows you to specify a custom filter using the syntax of a SQL WHERE
clause. The length of the filter formula must not exceed 500 characters. This option is not available for
OpenEdge services. For more information about filtering by formula, see Filtering by formula on page 445.
• Search criteria: The Search criteria condition allows you to filter using OpenEdge ABL syntax. This option
is only available for OpenEdge services. For more information about filtering by search criteria, see Filtering
OpenEdge Service objects by search criteria on page 446.
Some fields have special tokens that can be used in filters. Do not use quotation marks around tokens or
keywords.
• For text fields, you can create "or" filters by using the is one of operator and separating multiple values
with commas. For example, Sales, Marketing looks for either Sales or Marketing.
• For user lookup fields, use CURRENT_USER to represent the current user.
444 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Working with views
• For date fields, you can use special tokens derived from the current date:
Token Description Example
TODAY 12:00 AM of current date 08/18/2015
WEEK First day (Sunday) of current week 08/09/2015
MONTH First day of current month 08/01/2015
QUARTER First day of current quarter 07/01/2015
YEAR First day of current year 01/01/2015
Note: The value of the TODAY token is 12PM+1ms of the current day in the time zone of the current user
for date/time fields; for date fields, its value is either the beginning (for the greater than operation) or
the end (for the less than operation) of the current day.
You can add or subtract integer numbers from tokens to specify a date not in the current time period. For
example:
• To filter by the first day of next week, use the condition WEEK+1
• To filter by the current week (from Sunday to Saturday), use the conditions date>=WEEK AND
date<WEEK+1
• To filter by the previous month, use the conditions date>=MONTH-1 AND date<MONTH
• To filter by the previous and current year, use the conditions date>=YEAR-1 AND date<YEAR+1
Filtering by formula
While filtering views based on expressions offers a lot of flexibility, it does not cover all possible filtering scenarios.
For this reason, Rollbase offers filtering by a formula. To filter a view by a formula, click the drop-down menu
next to Filter Conditions and select Formula:
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 445
Chapter 7: Customizing the user experience
The page displays the Formula Helper, where you can define the formula.
You write a filter formula using the syntax of a SQL WHERE clause. The formula may include any stored fields
(i.e. non-dynamically computed fields), SQL operands (including LIKE, IN, AND, OR, and NOT), helpers (such
as the current user ID, customer ID, portal user ID, etc.) and the following special functions:
• #YEAR(date) returns the date's year as an integer
• #MONTH(date) returns the date's month as an integer in range 1 - 12
• #DAY(date) returns the date's day of month as an integer
• #IF(expr, val1, val2) returns val1 if expr evaluates to true, val2 otherwise.
When using an object's field in a formula, you must use the field's integration name. The Formula Helper area
can help you find the integration name. As shown below, if you select the field from the Select Merge Token
field, the Copy Merge Token field displays its integration name. Copy this name and use it in the formula. The
following simple example of a filter formula filters last names in a room reservation application to only view
reservations where the last name is Beauchamp:
A filter formula can include tokens derived from the current date as shown above.
Note: The length of a filter formula must not exceed 500 characters.
Filtering OpenEdge Service objects by search criteria
For OpenEdge Service objects, Rollbase offers filtering by search criteria to enable you to construct a complex
filtering criteria in OpenEdge ABL syntax.
Note that filtering by search criteria is available only to the OpenEdge Service objects that implement the
orderby parameter in a JSON filter string. This must be done as part of developing your JSDO catalog. For
more information on the recommend parameters to be implemented in your JSDO catalog file, see Creating
an application from OpenEdge data on page 588.
The search criteria supports the following search conditions:
• String
• Numeric
• Logical
• Date
446 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Working with views
The following table provides search examples:
Table 3: Search criteria examples
Condition Valid Operators Search criteria or Filter clause examples
String ABL operators for ABL CHAR and
LONGCHAR data types • Name='Girish'
• Name<>'Girish'
• Name BEGINS 'Gi'
• Name MATCHES '*ri*'
• NOT(Name MATCHES '*ri*')
• (Name='John') AND
(Last-name='Lennon')
• (Name <> 'Girish' AND Name <>
'John' AND Name <> 'Lennon')
Note: The name of a field in your search
criteria is the field name in the JSDO catalog.
That is, if the JSDO Catalog has Last-name
but the Rollbase field name is Lastename, you
must use the field name, Last-name in your
search criteria.
Numeric ABL operators for ABL INTEGER, INT64, and
DECIMAL data types • Age=20
• Age<>20
• Age>=20
• Age=?
• Age<>?
• Age=20
• Age=20
Logical ABL operators for LOGICAL data types
• SENDNEWSLETTER=Bool
• SENDNEWSLETTER=NOT Bool
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 447
Chapter 7: Customizing the user experience
Condition Valid Operators Search criteria or Filter clause examples
Date ABL functions for DATE, DATETIME, and
DATETIME-TZ data types • DOB=DATE (04, 13,1987)
• UPDATEDON<=TODAY
• ORDEREDON=DATE (OrderDate)
• UPDATEDON=MONTH (TODAY)
• DOB<>YEAR(DATE (04, 13,1987))
• ORDERDATE=WEEKDAY (TODAY)
For information on ABL operations and functions, refer to the OpenEdge ABL Reference guide in the OpenEdge
documentation set.
Editing a view on an application page
You can edit views and records directly on an application page.
See the following topics for details:
• Inline editing on page 448
• Dynamic filtering on page 451
• Color coding rows on page 453
• Column data options on page 455
Inline editing
Records in a view can be edited inline just like fields on view record pages.
448 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Working with views
To edit a view record inline:
1. Double-click a row to open the inline editing options available for that row.
2. Enter new values for the row as desired.
3. When you have finished editing the record, click save or cancel.
You can choose to disable the inline editing option for the entire List View grid by selecting the Disable Inline
Edit checkbox in Page Designer. The Disable Inline Edit option is disabled by default.
This property is available for all record list views and related lists. It is applicable only for NewUI.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 449
Chapter 7: Customizing the user experience
450 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Working with views
Dynamic filtering
You can dynamically apply a filter to a view on an application page. This includes views on record list and
selector pages and lists of related records on view pages. To define a filter, click Filter in the toolbar and select
one of the options from the drop-down menu.
This allows you to temporarily modify the filter conditions of the view without changing the saved version.
For information about standard filters and filter expressions, see Filter criteria on page 443.
For information about formula filters, see Filtering by formula on page 445.
Click Apply Filter to reload the view once you have made changes and click Clear Filters to go back to the
default filter conditions of the saved view.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 451
Chapter 7: Customizing the user experience
Administrators can control whether the control for advanced filter options (Standard, Formula, and Expression)
is visible on the page by setting the property Hide Advanced Filtering on the view component in the page
editor. They can also disable filtering on the page by setting the property Disable Filtering on the view control.
Administrators can also control whether advanced filter options are available using the following JavaScript
properties:
• showAdvancedFilterTypes on page 1146 — Determines whether the control for advanced filter types is
displayed
• showBooleanOperators on page 1148 — Determines whether the control for Boolean operators is displayed
CustomEvent for Dynamic Filter Rendering
452 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Working with views
You can delay rendering the filter section when using for the first time. If you have JavaScript to customize
filter component, adapt it to run the code after the filter component is rendered. You need to listen to the custom
event rbs_dynamicFilterRendered and execute your customization code in the callback function as exemplified
below.
<script>
try {
if (!rbf_isNewUI()) {
throw 'This Script is written for New UI';
}
var onFilterRender = function ( event, eventData) {
// Now customize the filter the way you want.
// Event Data: { filterEle: theFilterElement, cellId: theCellId, cellOrgId:
theCellOriginalId }
};
rb.newui.util.addEventListener(rb.newui.util.customEvents.rbs_dynamicFilterRendered,
onFilterRender);
}
catch (err) {
if (console) {
console.log(err);
}
}
</script>
Color coding rows
You can define colors to highlight records that meet certain criteria. On an application page where the filter
button is available, select Edit Row Colors from the view selector:
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 453
Chapter 7: Customizing the user experience
The Color Code View page opens. You can define one or more filters and select the color to use for each. If
the record meets more than one criterion, the first applicable color is used. The following example shows two
filters, one where Author starts with A and the second where Author starts with B:
The example filter renders the row colors as shown:
454 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Working with themes
Column data options
You can change the way columns are displayed in a view on an application page in the following ways:
• Sorting — To sort a column, click the column header.
• Selecting columns — To select columns to display, select or deselect columns from the Columns menu.
The selected columns for that view become part of the user's preferences and the view will contain the
same columns for that user until the user changes the column selection.
• Moving columns — To move a column, drag the column header to a different location. The new column
order is only valid for the current login session.
Working with themes
If you use the new Rollbase UI, you can change the look and feel of a Rollbase application by changing its
theme. New and existing applications use the Default theme, which has a white background with a blue menu
bar and orange buttons. Rollbase provides a variety of built-in themes and you can select a different theme for
each application. You can also select a default theme for all of your applications. See My Preferences on page
716 for more information.
The following screenshots show different built-in themes applied to an application:
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 455
Chapter 7: Customizing the user experience
456 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Record List Options, Mobile and Tablet Support
You change the theme of an application on the application setup page from the Theme Preview mode. The
theme is applied to that application for all users. In the Theme Preview mode, three color dots are displayed
before each theme name. These are the main colors of the theme. See Using the Theme Preview mode on
page 120 for more information.
The following screen shows an application in the Theme Preview mode:
Note: You can further customize the user interface of an application by using custom CSS. See Custom CSS
on page 507 for details.
Record List Options, Mobile and Tablet Support
Improved support for mobile devices
Rollbase offers improved support for the responsive user interface on mobile devices, with a focus on tablets.
Only deployed applications are available on mobile devices; setup pages are not included. Automatic
modifications to the user interface on tablets and smartphones, detailed below, are designed to provide a better
user experience on each type of device.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 457
Chapter 7: Customizing the user experience
The following screen shows an application page on a tablet:
The following screen shows the same application page on a smartphone:
Mobile support for both tablets and smartphones
458 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Record List Options, Mobile and Tablet Support
Support on both tablets and smartphones include the following:
• The default font size on a mobile device is the desktop font size plus 2 (14pt by default).
• The Rollbase menu:
• Is rendered in non-administrative mode.
• Includes a Log Out menu item.
• Does not include the Subscription Details menu item.
• The application switcher is rendered in non-administrative mode.
• On record list pages:
• Global search is rendered in non-administrative mode.
• The page menu only contains the new record menu item.
• The page options menu is not displayed.
• The view selector is not displayed if there is only one view available.
• Inline editing is disabled.
• Only the refresh action is available for charts and gauges.
• You can sort columns (short press on column header) and change column order by pressing longer and
dragging a column to the desired location.
• The branding header and footer are not displayed.
• On record view pages, the only action in the more actions menu is Delete.
Tablet support
This release focuses on improving the user experience on tablets with the responsive user interface.
The tablet-specific user interface includes the following:
• The user profile menu does not include the Log Out menu item. Instead, Log Out is in the Rollbase menu.
• The view selector does not contain any administrative actions (cannot edit, color code, or clone a view).
• Report links only contain Email this Report.
Smartphone support
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 459
Chapter 7: Customizing the user experience
The smartphone-specific user interface includes the following:
• Buttons on the page toolbar have no text:
• On record list pages, the list component has no Actions column.
• On record view pages that contain a grid component with related records, there is no Attach button (on
desktops and tablets, an Attach button is in the grid toolbar):
The screen below shows the Attach Furniture button on a tablet:
460 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Record List Options, Mobile and Tablet Support
• Report links do not have any actions.
• There is no Actions column in record lists.
• There is no user profile menu.
• The filter button is on the record list header.
• The Columns button is on the record list header.
• There is no quick create button on record list pages. You can still create records using the new record page.
• On the record list page toolbar, Export is not displayed unless the property
rb.ui.options.showGridExportFunctionOnSmartPhone is set to true.
• On the record list page toolbar, the actions menu is not displayed unless the property
rb.ui.options.showGridMoreActionOnSmartPhone is set to true.
• The view selector has no label.
• The Rollbase menu does not have the Recycle Bin or Recent Items menu items.
New record list page options
Record list pages now include the following options:
• Support for infinite scrolling — You can specify infinite scrolling for the record list instead of paging through
records. This is particularly useful on mobile devices, where users expect infinite scrolling in their apps.
• Support for specifying list height — You can specify the height of the record list in the page editor. This is
useful for:
• Supporting multiple device sizes with a single policy
• Pages where the record list is the only element on the page and you want it to take up all of the available
height of the browser window — when combined with infinite scrolling, this provides a very natural
experience on mobile devices.
• Pages that contain other elements, such as charts, reports, or gauges — rendering a smaller list height
allows room to display other page elements.
The height can be specified using the following:
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 461
Chapter 7: Customizing the user experience
• px — The height of the list in pixels
• em — The height of the list, where the unit is the font size of the container (which is the parent element)
• rem — The height of the list, where the unit is the font size of the root element (which is the html element;
see Custom CSS on page 507 for examples of rules that use the html element.)
• % — The height of the list in relation to the available space on the page without having to scroll (the view
port)
• empty or -1 —
If no unit is specified, defaults to px.
You enable/disable infinite scrolling and set the list height in the Properties drop-down menu for a view
component in the page editor as shown below:
User interface changes on record list page
On record list pages, the column selector has been replaced with a Columns button next to the Filter drop-down
menu. The functionality stays the same; the Columns button allows a user to select which columns to display
in the record list.
462 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Record List Options, Mobile and Tablet Support
Old column selector:
New Columns button:
On record list pages, the Delete button no longer contains text:
Customizing menus
You can customize how the menus in the application header are rendered. The following options are available
in the javascript object:
rb.newui.options.customizeMenuDisplay:
• rb.newui.options.customizeMenuDisplay.customOverflowForMenus.overflowMenusPerColumn
— Sets the number of menu items per column in the overflow menu. Defaults to 10.
• rb.newui.options.customizeMenuDisplay.customContainerForChildMenus.enableIfChildMenusGreaterThan
— When a tab has many child menus, you can specify at what point (in terms of the number of child menus)
the child menus should be split into multiple columns instead of in a single column. Defaults to 10.
• rb.newui.options.customizeMenuDisplay.customContainerForChildMenus.childMenusPerColumn
— Sets how many child menu items are displayed under each column. Defaults to 10.
You can also customize the page menu to set the number of menu actions to be displayed in each column
using rb.newui.options.customizeMenuDisplay.pageTitleMenus.childMenusPerColumn.
Defaults to 10.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 463
Chapter 7: Customizing the user experience
User changes to record list page are saved on a per view/per device basis
When a user makes changes to the record list on a page, such as swapping columns, hiding columns, or
resizing columns, those changes are now saved per view and per device. For example, if a user makes these
changes on their smartphone, the changes will not appear on their desktop.
Enhanced page construction log
With the New UI, the entire page renders on the client side using json data returned from Rollbase. page
Construction logging has been enhanced on client side for New UI pages. This will assist in quickly debugging
and troubleshooting any possible issues.
The page construction log includes:
• The page components rendered (sections, page cells, etc.)
• The order in which the components were rendered
• The time required to render each
To generate the page construction log, execute the following JavaScript statement on the browser console:
rb.newui.page.PageContext.printPageConstructionLog()
Sample Log:
PageContext [ Time: 27 ms ]
CustomSideBar [ Time: 2 ms ]
HeaderFooter [ Time: 183 ms ]
Page - 90106 [ Time: 169 ms ]
Section - 221353 - All Object1s [ Time: 136 ms ]
Cell - 221354 [ Time: 109 ms ]
Section - 227222 - HTML Section [ Time: 6 ms ]
Cell - 227223 [ Time: 1 ms ]
Section - 234194 - Section non-mobile [ Time: 5 ms ]
Cell - 234195 [ Time: 1 ms ]
In addition, you can enable more verbose logging at the time of page creation in browser client. To enable,
add following script component to an application's custom sidebar or header:
<script id="executeBeforeUIStarts">
(function () {
try {
//execute only for new ui...
if (!rbf_isNewUI()) {
throw 'This Script is written specific to New UI Context';
}
rb.newui.page.PageContext.showPageConstructionLog(true);
}
catch (err) {
if (console) {
console.log(err);
}
}
}) ();
</script>
464 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Pagination Control, Responsive Image Fields, and Custom Reports
Sample log printed on browser console:
Creating - HeaderFooter
Completed - HeaderFooter [ Time: 139 ms ]
Creating - Page - 733968
Creating - Section - 734015 - All Message2s
Creating - Cell - 734016
Completed - Cell - 734016 [ Time: 300 ms ]
Completed - Section - 734015 - All Message2s [ Time: 122 ms ]
Creating - Section - 759955 - New Section
Creating - Cell - 759956
Error appending inline script: TypeError: Cannot read property 'util' of undefined
Completed - Cell - 759956 [ Time: 1 ms ]
Completed - Section - 759955 - New Section [ Time: 2 ms ]
Completed - Page - 733968 [ Time: 145 ms ]
Automatic addition of RTL (right to left) library
The RTL version of the Bootstrap library version 3.3.4 is now automatically included for the application when
you switch to RTL mode by adding &rtl=true. Prior to this release, an administrator needed to include this library
in a custom header to support RTL mode.
Performance improvements
Depending on the page type and its content, overall rendering performance of pages has been improved by
10% to 20%.
New client-side JavaScript functions to detect mobile devices
The following JavaScript functions are now available for script customization (can be used in custom sidebar
or custom header):
• rb.newui.util.isMobile() — Returns true if Rollbase is running on a mobile device (tablet or smart phone)
• rb.newui.util.isTablet() — Returns true if Rollbase is running on a tablet
• rb.newui.util.isSmartPhone() — Returns true if Rollbase is running on a smartphone
See Client-side JavaScript on page 1131 for more information.
Updated CSS rule for Microsoft Edge browser
In the previous release, an html element could contain the x-k-edge CSS rule. In this release, the CSS rule
k-edge is also supported. Support for the rule x-k-edge is maintained in this release but will be removed in
the next release.
Pagination Control, Responsive Image Fields, and
Custom Reports
Pagination control at top for record list components
A new property, Show Pagination at Top, is available in the page editor for record list components. When
checked, the component includes a pagination control at the top of the component in addition to the bottom of
the component.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 465
Chapter 7: Customizing the user experience
The following screen shows a Records List page with this property enabled:
466 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Pagination Control, Responsive Image Fields, and Custom Reports
Sizing record list columns as an HTML table
Rollbase now sizes record list columns as an HTML table by default. This reduces white space in columns and
allows more columns to be visible when not all columns fit on the screen. If you do not want this feature enabled,
you can turn it off by deselecting the component's property Size Column as Html Table in the page editor:
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 467
Chapter 7: Customizing the user experience
The following screen shows a record list page that where columns are not sized as an HTML table:
The following screen shows the same page where columns are sized as an HTML table. Note that more columns
fit on the screen:
468 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Pagination Control, Responsive Image Fields, and Custom Reports
Responsive image fields
You can now specify that all Image Upload and Shared Image fields are responsive to the device size. The
following screens show a responsive image field on different screen widths.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 469
Chapter 7: Customizing the user experience
If you want image fields to be responsive, set the property rb.newui.options.useResponsiveImage to
true in a custom sidebar script that executes before the UI starts. If responsive images are enabled, Rollbase
ignores the width and height properties set for images in the page editor. See useResponsiveImage on page
1152 for more information.
Role-based landing pages
You can now configure a landing page for a role. The configured landing page includes the application page
and the tab to open. When a user with that role logs into Rollbase, the configured page opens with the configured
tab selected.
To configure a landing page for a role:
1. Navigate to the Setup Home page.
2. Select Roles.
3. Select Pages next to the role for which you want to configure the landing page.
470 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Pagination Control, Responsive Image Fields, and Custom Reports
The Assign Page Versions page opens.
4. Select the Configure landing page for the role check box.
5. From the Select Application drop-down list, select an application.
6. From the Select Tab drop-down list, select a tab.
7. Click Save. When a user with that role logs in, the configured application will open with the configured tab
selected.
Ability to change uploaded file without changing its URL
Prior to this release, if you changed a File Upload field by uploading a different file, a new URL would be
generated for the uploaded file. This could result in outdated links for applications using that URL. In this release,
the URL for the newly uploaded file does not change.
Note: This feature is only for File Upload fields that are publicly available. Configure a File Upload field to be
publicly available by selecting Make files publicly available for that field.
Additional page sizes for PDFs
For document templates, HTML template reports, and document template reports, Rollbase now supports all
PD4ML-supported sizes for Page Size as well as custom sizing. In all cases, you must select Render as PDF
to enable the Page Size option.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 471
Chapter 7: Customizing the user experience
The following screen shows the Page Size options for a document template:
Conditional field-level permissions
You can now specify conditional formulas for field-level view and edit permissions. Each formula must return
true or false. If the formula returns true, that permission is granted for the specified role. If the formula
returns false, that permission is not granted for the specified role.
For View or Edit permission, you can specify Yes, No, or Conditional Formula by selecting a radio button
for each role as shown below:
472 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Pagination Control, Responsive Image Fields, and Custom Reports
The following screen shows a condition formula. In this example, the createdBy field (whose value is a user
link), must equal the current user to grant edit permission on the Comments field.
Note the following when implementing conditional edit permission:
• For performance reasons, keep conditional formulas short.
• To grant edit permission on a field, you must also grant view permission on that field. This applies to both
non-conditional and conditional permissions.
• Edit permission is granted for any use that creates or updates records, including Edit pages, Mass Update
pages, and inline editing.
• For mass updates, Rollbase updates only those records for which the condition formula returns true.
• When updating records using SOAP, REST, and Server APIs, Rollbase does not use conditional permissions.
The REST method getPermissionsByRole now outputs conditional for fields with conditional permissions.
See getPermissionsByRole on page 1231 for details.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 473
Chapter 7: Customizing the user experience
The REST method setPermissionsByRole now includes the following parameters for conditional permissions:
• viewConditionScript — The condition script for view permission as a base64-encoded string. To grant
conditional view permission, specify view in the permissions parameter in addition to this parameter.
• editConditionScript — The condition script for edit permission as a base64-encoded string. To grant
conditional edit permission, specify edit in the permissions parameter in addition to this parameter.
See setPermissionsByRole on page 1268 for details.
For more information about field-level permissions, see Setting field-level permissions on page 659
New administrative permissions for non-administrative roles
This release introduces new administrative permissions for non-administrative roles. This allows you to appoint
users with a particular role to be able to manage roles and users, and to enable and disable support access
from the master tenant, without granting them full administrative permissions.
The following permissions are now available:
• Manage Roles — Users with this permission can create and edit roles. They can only create roles with the
same set of permissions as their own role or with a subset of those permissions. They cannot manage the
Administrator role or their own role. They cannot assign any administrative permissions to any role.
• Manage Users — Users with this permission can edit users if they have the appropriate permissions on
the User object. They cannot assign the Administrator role to a user.
• Configure Support Access — Users with this permission can enable and disable support access from the
master tenant.
New post install script for applications
You can now create a post install script that will be executed after an application is installed during customer
creation. For example, if you want the new customer's first user to have a custom role instead of the default
Administrator role, you can write a post install script for the Rollbase application that changes the first user's
role to a custom role (see New administrative permissions for non-administrative roles on page 474). If multiple
applications are installed during customer creation, Rollbase executes each application's post install script in
the order in which the applications are installed.
To create a post install script for an application:
1. Navigate to the setup page for an application to be installed during customer creation.
2. Click Post Install Script.
3. Click Edit Post Install Script.
4. Edit the script as desired.
474 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Enhanced Smart Images, Notifications, and Others
Note:
If the post install script's purpose is to create a tenant with no administrator, you can access the automatically
created user with the Administrator role and change the role to a custom role with some administrative
permissions. For example:
var objId = rbv_api.selectNumber
("SELECT id FROM USER where role =90"); // Administrator role's original ID is always
90
var role = rbv_api.stringToJson(rbv_api.getRoleById("868114")); // Custom role with
admin permissions
rbv_api.setFieldValue("USER",objId,"role",role.code); // Set user's role to custom role
5. Click Save.
New shared property AllowAdminLessTenant
The new shared property AllowAdminLessTenant, when set to true, enables tenants without administrative
users. Does not apply to the master tenant. Defaults to false.
See New administrative permissions for non-administrative roles on page 474 for information about administrative
permissions for non-administrative roles.
See New post install script for applications on page 474 for information about creating a tenant without
administrative users.
Custom reports (beta)
This release includes a beta version of custom reports. A custom report can include multiple sections and
sub-sections with no limit on the number of sections or the depth of sub-sections. You can use custom reports
to build rich, highly customized documents to present your application's data.
Features of custom reports include:
• A Report Builder where you design and organize report sections and sub-sections
• Special tokens you can use to easily access records used in the report
• The ability to preview a report directly from the Report Builder
• A Table of Contents section that you can place anywhere in a report
• A section that loops through a list of records. You can control the order of execution and filter the set of
records on which to execute the loop.
• A Sub-Report section that inserts an existing report into the custom report.
For more information about custom reports, see Selecting a Custom Report Type on page 309.
Enhanced Smart Images, Notifications, and Others
The following describe new features and changes related to the user interface and end user experience:
• Smart image uploading and rendering on page 476
• Support for simplifying import procedure on page 476
• Ability to position notification messages on page 478
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 475
Chapter 7: Customizing the user experience
• Trigger screen improvements on page 480
• Text change for new record button on record List pages on page 481
Smart image uploading and rendering
The smart image feature provides automatic resizing of images:
• Specify a maximum size in Image Upload field properties, to have Rollbase automatically resize images
when users upload them.
• Enable a dynamic image preference that causes Rollbase to automatically store images that are 992px or
wider in four pre-defined widths (992px, 768px, 480px, and 50px) and to render the appropriate image. For
example, on record list pages, Rollbase uses the smallest image, but for view pages and pages that display
cards, Rollbase uses the image closest to but smaller than the device. The dynamic image preference
applies to all apps in a tenant. Images narrrower than one or more of the pre-defined widths will be stored
in the original size and the narrower widths. For example, an image with a width of 500px would be stored
at 500, 480, and 50.
Note: When you set the field property or preference, it applies to images uploaded after the setting, not to
previously stored images.
To have Rollbase automatically resize images on upload, use the new Image Upload field property Maximum
Image Size and specify a value in pixels. For landscape images, Rollbase applies the maximum size to the
width. For portrait images, Rollbase applies the maximum size to the height. When Maximum Image Size is
specified, Rollbase ignores the Maximum File Size property. Rollbase resizes images only if they are larger
than the specified value.
To set the dynamic images preference:
1. From the Setup home screen, click Preferences under Administration Setup.
2. In the Dynamic Image Resize Settings area, select the Enable resizing and storing images for different
device form factors check box and save your changes.
Support for simplifying import procedure
This release allows you to simplify the end user procedure for importing data from spreadsheets or CSV files
to create records. You can create an import map and a custom way to invoke import, such as a button, link, or
trigger that passes in the map id. Then, users do not need to select the import action (create new record) or
the import map, they can simply select the file. To avoid confusion between the simplified import and the default
import, you can label your button or link explicitly and/or you can hide the default import button and menu item.
For example, the following screen shows a simplified import button as part of the new record page toolbar.
476 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Enhanced Smart Images, Notifications, and Others
When end users click the button, a streamlined Import page opens where the user selects a file and clicks
Next to begin the import.
Note: If users need to update or delete records from spreadsheets or CSV files, they will need to use the default
import procedure that is initiated from the Import button or menu item on record list pages. If you do not need
to support update and delete in this way, you can hide these items as follows:
• To hide the Import button, open the record list page in the page editor and deselect the property Show
Import Link from the record list component.
• To hide the Import menu item, deselect View permission for the object's Menu: Import for any role for
which you want it hidden.
High level steps for simplifying the import procedure
To enable a simplified import procedure, follow these high level steps:
1. Create the import map to specify the mappings between an object and the import source.
2. Using a mechanism that supports a URL, such as a button, trigger, or link, construct a URL to open the
object's Import page and pass in the import map ID. Use the following parameters of the
rb.newui.util.addQueryParameter() method to supply the required information for the URL:
• importMode — An integer representing the import mode. Currently, the only valid value is 0, which
creates new records.
• destId — The ID of the current page (available from the PageContext object as shown below)
• oMapId — The original ID of the import map to use to import data
Example for creating a simplified import button
To create a simplified import flow similar to the one shown in the screen shots above, after you have created
an import map and have saved its ID, follow these steps:
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 477
Chapter 7: Customizing the user experience
1. Open the object definition.
The example demonstrates simplified import for the Title object.
2. Jump to the Buttons section and click New Button
The New Button screen opens.
3. Set the fields as follows:
• Enter a Display Name
• Leave the default Behavior set as: Run client-side JavaScript.
• From the Template Helper in the Button Script editor, in the field right of the object name, select the
URL to Import Page.
The token shows in the field at the bottom of the Template Helper, for example {!#LINK.Title#import}
for the Title object.
• Copy the token to use in the script.
• In the script area of the editor, construct a URL and add the logic to open the Import page with the
rb.newui.util.addQueryParmeter() method.
The following shows the example code for the Title object with a map ID of SIi4gXEIR5OeNvwwK6NeFA.
The JavaScript formula for the button adds these parameters to the Import page URL and sets the
JavaScript window.location object to redirect the user to that URL:
var url = '{!#LINK.Title#import}';
url = rb.newui.util.addQueryParameter(url, 'importMode', '0');
url = rb.newui.util.addQueryParameter(url, 'destId',
rbf_getPageContext().getPageId());
url = rb.newui.util.addQueryParameter(url, 'oMapId', 'SIi4gXEIR5OeNvwwK6NeFA');
window.location.href = url;
4. Select the pages on which you want the button to appear.
5. Save the button.
Ability to position notification messages
For apps that use the New UI, you can now choose where to position notification messages: the default upper
right corner or the lower right corner.
Set notification message position as follows:
1. Navigate to the application settings page.
2. Click Edit to edit application properties.
3. Scroll to the New UI Specific Settings section.
4. From the Notification Position drop-down, select the position for notifications:
478 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Enhanced Smart Images, Notifications, and Others
Selecting the option Bottom Corner positions notifications for that application as shown below.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 479
Chapter 7: Customizing the user experience
Trigger screen improvements
The following trigger screens have been redesigned for better usability and organization:
• The New Trigger screen consumes the available space correctly, sizes the columns appropriately (in
particular, when the language is not English as shown below), and avoids rows that are too tall.
• The trigger create and edit screens now present the type and name of the trigger first, and all trigger
timing-related fields are grouped together as shown below.
• The trigger view page uses screen space more efficiently, and for Object Script triggers, provides more
space for the Object Script editor. The system information and the second toolbar at the bottom of the
screen. The following shows the new trigger view layout:
480 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Improved Editing Capabilities
Text change for new record button on record List pages
Previously, the new record button on record List pages included the word New. This caused an issue for
multilingual applications since "new" can be translated in different ways in some languages. Now, the button
simply shows the plus symbol and the object name.
The old button looks like this:
The new button looks like this:
Improved Editing Capabilities
New features in this release that improve and extend editing capabilities include:
• Card Editor tools for adding custom scripts and CSS styles on page 482
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 481
Chapter 7: Customizing the user experience
• Improved table tools in rich text editor for Text Area fields on page 487
• Ability to select devices on which to display page tabs on page 488
• Ability to hide or show Export button on record List pages on page 489
• Ability to hide or show empty fields on View pages on page 490
• Ability to remove or show field labels on Edit pages on page 491
• New CSS class to size text areas on page 491
Card Editor tools for adding custom scripts and CSS styles
After you create a new card template, you can edit it. In this release, the Card Tools menu of the Card Editor
allows you to add:
• Custom scripts that Rollbase executes before and/or after a card renders to customize its contents. For
example, you can insert text or add widgets, such as Kendo UI controls
• Custom CSS styles
The new card tools support the following:
• Add/Edit Card Script — Lets you customize a card by executing scripts.
482 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Improved Editing Capabilities
• Script that you add in the first box runs as soon as data is fetched from the server and before rendering
the cards. It takes three arguments:
• cardData — An array of the values used to render the card
• dataSource — The Kendo Datasource used by the card
• cardListview — The KendoListView (KendoMobileListView for mobile devices ) component
that renders card items
The following example prepends Custom_ to the name of each title record:
var someData = "Custom_" + cardData["name"];
cardData["name"] = someData;
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 483
Chapter 7: Customizing the user experience
The following screen shows the resulting cards on a tablet:
• Script that you enter in the second box runs once after rendering all cards on the page. It takes three
arguments:
• cards — A list of all cards on the page
• dataSource — The Kendo Datasource used by the card
• cardListview — The KendoListView (KendoMobileListView for mobile devices ) component
that renders card items
484 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Improved Editing Capabilities
The following example adds a kendoSlider component to each card on the page:
if(cards){
//Iterate through all card list item
for(var i=0;i<cards.length;i++){
var card = $(cards[i]);
//Find an element where we want to render kendo slider
var tempSliderEle = card.find('.temperature');
tempSliderEle.show();
var tempSlider = tempSliderEle.data('kendoSlider');
var recUid = card.attr('data-uid');
if(recUid){
var rec = dataSource.getByUid(recUid);
var recId = rec["recordId"];
var currTempVal = rec["Set_Temperature"];
var confirmMsgEle = card.find('.confirmTempChange');
if(!tempSlider){
tempSliderEle.kendoSlider({
max:100,
min:0,
value:currTempVal,
dragHandleTitle:'Drag to change temparature',
tickPlacement:'bottomRight',
recId:recId,
currTempVal:currTempVal,
});
}
}
}
}
The following screen shows the resulting cards on the page:
• Add/Edit Card Style — Lets you add custom CSS styles. By default, the styles apply to all sections on a
page. This typically works just fine. But if a page contains multiple list views, and you want different styles
for each, you can make the style specific to the page section that contains the list. To apply a style to a
specific section, use the section original ID prefixed by #rbi_S_ . You can find the section ID by opening the
page in the page designer and selecting the section. For example, to identify a section with the original ID
of ZR_XI0e5TUO5BQIVgzgeIA, use:
#rbi_S_ZR_XI0e5TUO5BQIVgzgeIA
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 485
Chapter 7: Customizing the user experience
486 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Improved Editing Capabilities
Improved table tools in rich text editor for Text Area fields
When you create or edit a Text Area field, you can select the Use Rich Text (HTML) Editor check box to
enable the rich text editor for end users. In this release, the rich text editor has been enhanced in the following
ways:
• You can now drag the table outline to resize columns or rows.
• A new Table Wizard allows you to create table attributes while creating a new table or editing an existing
table.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 487
Chapter 7: Customizing the user experience
Ability to select devices on which to display page tabs
The page Rollbase creates for viewing record details contains two tabs by default as shown in the screen
below.
You can add tabs to New, Edit, and View pages. Now, you can also select the devices on which each tab will
display. By default, all default and newly added tabs will be shown in all devices.
To select which devices you want a tab to show on, follow these steps:
1. Navigate to the page that contains the tab.
2. Open the Properties menu for the tab as shown below:
3. Select the appropriate device(s).
See Page tabs on page 378 for more information about page tabs.
488 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Improved Editing Capabilities
Ability to hide or show Export button on record List pages
Administrators can now hide or show the Export button on record List pages from the page editor by selecting
or deselecting Hide Export in the Properties menu for the view component:
The following graphic shows the page with the Export button:
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 489
Chapter 7: Customizing the user experience
The following graphic shows the page without the Export button:
Ability to hide or show empty fields on View pages
Administrators can now hide or show specific empty fields on View pages from the page editor by selecting or
deselecting Hide Empty Field in the field's Properties menu.
490 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Improved Editing Capabilities
Ability to remove or show field labels on Edit pages
Administrators can now remove or show specific field labels on Edit pages from the page editor by selecting
or deselecting Remove Label in the field's Properties menu. If a field with some value is selected for removal,
the field will not be visible in the UI but, it's value will remain visible. Previously, hiding field labels on Edit pages
required writing code. See removeFieldLabel() on page 1143 for information about hiding field labels
programatically.
Note: For field types such as a checkbox, formulas, templates, image upload and integration link, the Hide
Label checkbox exists while creating the field. Both Hide Label and Remove Label are enabled by default.
However, the Remove Label functionality takes precedence.
New CSS class to size text areas
A new CSS class, rbs-editField-valueContainer-textArea, provides the same functionality for text
areas that the rbs-editField-valueContainer-richTextEditor class does for the rich HTML editor.
The new class defines the space consumed by a Text Area field inside of its container, with a default value of
95%. You can use any valid CSS attributes.
The following example sets the space consumed by text areas to 50%. In this example, it is set in a custom
sidebar script:
<style>
.rbs-editField-valueContainer-textArea {
width: 50%;
}
</style>
The resulting Edit page shows the Reviews text area on a tablet:
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 491
Chapter 7: Customizing the user experience
Record View and Record Edit Page Toolbars
Improvements in record view and record edit page toolbars
The page toolbar on record view and record edit pages has been improved.
On record view pages:
492 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Record View and Record Edit Page Toolbars
• The Previous, Next and Back to List buttons are now shown using icons (and the text becomes each
icon's tooltip).
• Workflow actions with the Render Button option, as well as custom buttons, are shown directly in the toolbar
if space is available. Otherwise they drop to the overflow menu (normal responsive capabilities).
• The order of buttons in the toolbar is:
1. Back to list
2. Previous
3. Next
4. Custom buttons and workflow actions
5. Edit
The following screen shows the toolbar with one custom button and two workflow action buttons:
The following screen shows the same toolbar for a narrower screen, with some buttons in the actions menu:
On record edit pages:
• Similar to a record view page, custom buttons are shown directly in the toolbar if space is available. Otherwise
they move to the overflow menu.
• The order of the buttons in the toolbar is the same as for record view pages (except there are no workflow
action buttons).
Rollbase calendar improvements
The Rollbase calendar has the following UI changes:
• Toolbar controls have been moved from within the canvas to the page header:
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 493
Chapter 7: Customizing the user experience
• The Show and Assigned To labels to the side of the drop downs menus have been removed; now View
and View Items Assigned To are within the drop-down menus:
Mouse rollover opens actions menu
On PCs, a mouse rollover or a click now opens the actions menu in a list of records as shown below. On devices
with touch screens, the menu requires the equivalent of a click (a touch).
Settings changed to Setup Home in Rollbase menu
In the Rollbase menu, what used to be Settings is now Setup Home to be consistent with the application
switcher.
494 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Performance Improvements
Workflow actions changed to picklist
In record list views, available workflow actions are now rendered as a picklist:
Ability to remove header and footer from printed records
You can remove the header and/or footer (and any buttons that appear in them) from a printout by customizing
record list pages. The newui.css contains two new classes, .rbs-popup-header and .rbs-popup-footer.
You can use the page editor to add a style using these classes to a specific record page. For example, to
prevent the printout or PDF from including either the header and footer, add the following style: @media
print{ .rbs-popup-header,.rbs-popup-footer{ display:none; }.
Performance Improvements
Performance improvements for page reloads
Rollbase is now supporting more AJAX requests instead of full page reloads. This improves the performance
on the client side (faster load and less data transferred) and on the server side (better scalability).
The following is the list of actions where Rollbase now does AJAX requests instead of full page reloads:
• When navigating top level tabs on the application menu bar
• When viewing a record (from a record list page to a record view page)
• When navigating back to the record list view from a record view page
• When viewing the next and previous record from a record view page
• When editing a record (Clicking Edit on a record view page). Note: Save is a full page reload.
AJAX requests can be turned off or on for an application with the following JavaScript properties, which you
set in a script in the custom sidebar. The script executes once, before the UI starts.
• rb.newui.options.applicationPage.ajaxNavigation — When set to false, disables page
navigation using AJAX requests. When set to true, enables page navigation using AJAX requests. This
property applies to all of the above actions for an application.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 495
Chapter 7: Customizing the user experience
• rb.newui.options.objectViewPage.recordNavigationAjax — When set to false, disables
page navigation between object records (previous and next) using AJAX requests. When set to true,
enables page navigation between object records using AJAX requests.
• rb.newui.options.tabMenuLink.ajaxNavigation — When set to false, disables navigation
between top-level tabs using AJAX requests. When set to true, enables navigation between top-level tabs
using AJAX requests.
The following example shows how to set these properties in a script. It enables navigation using AJAX requests
except for navigation between records and navigation between top-level tabs.
<script id="executeBeforeUIStarts">
if(rbf_isNewUI()){
rb.newui.options.applicationPage.ajaxNavigation = true;
rb.newui.options.objectViewPage.recordNavigationAjax = false;
rb.newui.options.tabMenuLink.ajaxNavigation =false;
}
</script>
In addition, Rollbase includes a new event, rb.newui.util.customEvents.rbs_pageRender. This event
occurs when the AJAX response has been received from the server and the content has been rendered in the
content element. You can handle this event in a JavaScript event handler in a script component to customize
the content on the page. See HTML and Script components on page 185 for more information about script
components.
As page loading using AJAX requests introduces a new navigation paradigm in Rollbase, it will break certain
assumptions and practices of customizing a Rollbase page by adding script components that execute on the
document.ready event. In order to be backward compatible and to allow you to absorb this change, page
navigation using AJAX requests is disabled by default in the Rollbase release for existing customers. You
should enable it in your test environments and identify any custom script issues when adopting the new page
navigation approach. You will need to rectify all such issues immediately as page navigation using AJAX will
be enabled by default in the 4.1 release.
For new customers (Rollbase 4.0 and later), page navigation using AJAX requests is enabled by default.
List in Selector pages is sized to fill the available space
As part of the enhanced suppport for mobile devices, a list on a Selector page is sized to fill the available space
by default. Administrators can override this by specifying a height for the list. The height can be specified in
the Properties drop-down for the list component in the page editor using the following units:
• px — The height of the list in pixels
• em — The height of the list, where the unit is the font size of the container (which is the parent element)
• rem — The height of the list, where the unit is the font size of the root element (which is the html element;
see Custom CSS on page 507 for examples of rules that use the html element.)
• % — The height of the list in relation to the available space on the page without having to scroll (the view
port)
• empty or -1 — The default (height of available space)
If no unit is specified, defaults to px.
Filtering improvements
Two new features improve filtering in applications:
• Ability to filter list of related records — On record view pages that display a list of related records, users can
now filter the list of related records. The screen below shows the new Filter button:
496 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Performance Improvements
• New JavaScrip0t flags to control showing/hiding advanced filter features individually:
• rb.newui.options.filters.showBooleanOperators — Controls whether the control for Boolean
operators is shown
• rb.newui.options.filters.showAdvancedFilterTypes — Controls whether the control for
advanced filter types is shown
The screen below highlights these components:
When both properties are false, the entire row is hidden to save vertical space:
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 497
Chapter 7: Customizing the user experience
Use these flags in custom sidebar code as shown below:
<script id="executeBeforeUIStarts">
rb.newui.options.filters.showBooleanOperators = true;
rb.newui.options.filters.showAdvancedFilterTypes = false;
</script>
Note: This code must appear in the custom sidebar. Adding it to the custom header has no effect.
Fields with input masks enforce mask during entry on new and edit pages
Prior to this release, input masks on Text and Phone Number fields were applied after the user entered a value
(when the field lost focus). Now, on new and edit pages, the input mask is enforced while typing a value into
the field. For example, for the Phone Number field below, the format of the input mask appears in the field
and the user is not allowed to enter incorrectly formatted data:
Additional OpenEdge SPA credentials
Rollbase Private Cloud now supports two additional credentials for OpenEdge SPA authentication:
• Super Admin Credential — Used when data is accessed from batch jobs and delayed triggers
• Guest User Credential — Used when data is accessed from portals
498 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Performance Improvements
You configure these credentials when configuring OpenEdge authentication:
CustomClassFilter provides ability to use custom Java objects in formulas (Private
Cloud)
In Rollbase Private Cloud, you can use custom Java objects in formulas. To do so, you must give Rollbase
permission to use the class(es) by specifying the CustomClassFilter property in the Shared Properties.
The value of this property should be a RegEx expression that matches the fully qualified name of the class(es)
you want to allow. See Shared Properties on page 786 for more information about shared properties.
Initial field focus on new/edit page load
On a desktop, when a new record page or edit page is loaded, the first field in the page gets focus. However,
this is disabled in tablets and smartphones because focusing displays the keyboard and obstructs the screen
view.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 499
Chapter 7: Customizing the user experience
Improved Recycle Bin, Kendo UI Library, and Settings
Record
This topic describes the following new features and changes:
• Alternative way to open Recycle Bin on page 500
• Cannot create or delete a Settings record on page 502
• Ability to populate existing records with default value of new field on page 501
• Support for enabling native date/time/date-time controls restricted to mobile devices on page 502
• Updated Kendo UI library on page 502
Alternative way to open Recycle Bin
The Recycle Bin screen supports purging or restoring of deleted items. For Administrators, the bin shows all
items deleted in the tenant, for users with other roles, it only contains the items they personally deleted. By
default, it has been available from the Rollbase menu. However, administrators could use a custom client-side
script to hide it. In this release Administrators can additionally show or hide the bin by user Role.
If the Recycle Bin is available for their role, users can now access it from the My Profile option on the profile
menu, which opens the My Profile screen:
500 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Improved Recycle Bin, Kendo UI Library, and Settings Record
Ability to populate existing records with default value of new field
When creating a new field with a default value, you can now select an option to populate existing records with
that default value. This option is available for the following field types:
• Text
• Checkbox
• Currency
• Decimal
• Integer
• Percentage
• Version Number
• Picklist
• Picklist (Multi-Select)
• Radio Buttons
• Group of Checkboxes
To select the option, assign a Default Value to the field and select the Assign values for all existing object
records now check box when creating the field as shown below.
Note: The setting only applies to new fields. If you update an existing field by adding a default value, existing
records will not be updated with the Default Value.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 501
Chapter 7: Customizing the user experience
Cannot create or delete a Settings record
A Settings object is available to administrators from Setup > Administration Setup > Account Administration.
This was intended to be a singleton object, since it stores tenant-wide settings. In this release, Rollbase enforces
the restriction so that exactly one Settings record exists in a tenant. An attempt to create or delete a Settings
record will fail.
For example, suppose you add the following script to an application page:
<script>
function my_callback(id) {
console.log("new record ID is: " + id);
}
rbf_createRecord("$SETTINGS", {"id":66778899}, my_callback);
</script>
Executing the script results in the following notification:
Attempting to delete the Settings record results in the following notification:
Support for enabling native date/time/date-time controls restricted to mobile devices
The application setting Use Native Calendar and Time Control has been changed to Use Native Calendar
and Time Control on mobile devices and only applies to mobile devices. Desktop devices use the Kendo UI
controls, which render and function better than native browser controls.
Updated Kendo UI library
The following table shows the previous and current versions of libraries used in Rollbase:
Library Previous version Current version
Kendo UI Professional 2016-2-607 2016-3-914
Font Awesome V4.6.3 V4.6.3 (not changed)
Bootstrap V3.3.6 V3.3.6 (not changed)
Bootstrap RTL V3.3.6 V3.3.6 (not changed)
JQuery V1.12.3 V1.12.3 (not changed)
502 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Filtering Features and Notification for Pending Changes
Filtering Features and Notification for Pending
Changes
Filtering features
This release includes two new filtering features:
• The ability to hide fields from filter options — When filtering the view on a record list page, users can select
fields on which to filter from a drop-down list. You can now set an advanced property, Allow filtering by
this field in List Views, on a field. When this property is unchecked, the field will not appear in the drop-down
list of fields.
• By default, filter options for a record list include advanced filter options, which include the ability to choose
between Standard, Expression, and Formula filters, as well as to choose whether All (AND) or Any (OR)
of the filter conditions are met. You can now hide these advanced filter options for record list components
in the page editor — A new property on this component, Hide Advanced Filters, controls whether these
options appear on the page:
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 503
Chapter 7: Customizing the user experience
When this property is checked, the advanced filter options highlighted below will not appear on the page:
504 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Filtering Features and Notification for Pending Changes
Notification when user navigates from page with pending changes
If a user modifies a record on a new, edit, or status change page and attempts to leave the page by navigating
away or closing it before saving the changes, a Confirm Navigation dialog will appear. This dialog gives the
user a chance to return to the page and save their changes.
This feature is not available on quick create pages.
You can control whether users are notified using the following:
• The property rb.newui.options.notify.onLeavingDirtyPage — This property has the value true
by default. To disable the notifications, set its value to false. See onLeavingDirtyPage on page 1151 for
details.
• The PageContext on page 1136 class method addDirtyPageNotifier() — Enables the notifications
• The PageContext on page 1136 class method removeDirtyPageNotifier() — Disables the notifications
A new PageContext on page 1136 method, isPageDirty(), returns true if the page has an object record form
with modifications.
See the newly documented JavaScript object PageContext on page 1136 and client-side method
rbf_getPageContext() on page 1115 for more information.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 505
Chapter 7: Customizing the user experience
Note: This feature uses a built-in browser feature that is not supported on Safari for the iPad.
rbf_getPicklistCode() and rbf_getPicklistCodes() client-side APIs now work with other
field types
These APIs now work with the following field types:
• rbf_getPicklistCode(): Picklist, Picklist (Multi-Select), Group of Checkboxes, Radio Buttons
• rbf_getPicklistCodes(): Picklist, Picklist (Multi-Select), Group of Checkboxes
New parameter to rbf_showOrHideField()
The client-side function rbf_showOrHideField() has a new, optional, Boolean parameter named
doNotHideResponsiveColumn. This parameter lets you control the responsive behavior on view and edit
pages when a field is hidden. The signature of the function is now rbf_showOrHideField(fieldName,
showField, doNotHideResponsiveColumn.
The value of the new parameter specifies whether to overwrite the column occupied by the hidden field:
• When true, Rollbase hides only the value of the field, not the column itself. The column for the hidden field
maintains its position regardless of the screen size.
• When false, Rollbase hides both the value of the field and its column. The value in the next column will
take its position.
• When not provided, defaults to false.
See rbf_showOrHideField() for details and examples.
JavaScript files available in uncompressed format
The following JavaScript files are now available in an uncompressed format:
• Options.js — Contains the default user interface options for the New UI
• CustomEvents.js — Contains definitions of custom events, event listeners, and event handlers
If you customize the UI with JavaScript, it will be helpful to review the contents of these files. You can find these
files at the following locations:
• Rollbase Private Cloud: http://localhost:8830/prod1/js/newui/ — For example, to view
Options.js when using a tenant running the PAS server, you would use the URL
http://localhost:8830/prod1/js/newui/Options.js.
• Hosted Rollbase: https://www.rollbase.com/prod1/js/newui/ — For example, to view
Options.js, you would use the URL https://www.rollbase.com/prod1/js/newui/Options.js.
506 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Programmatic client-side customization
Performance improvements when using OpenEdge Data Objects
This release introduces the following features that improve performance when using OpenEdge Data Objects
from an OpenEdge Data Object Service:
• Ability to cache OpenEdge Data Objects — Rollbase now caches Data Objects instead of fetching them
from the Data Object Service each time they need to be accessed. A new property on the object definition,
Clear Record Cache After, allows you to specify the number of seconds after which to clear the cache.
• Improved implementation for counting OpenEdge Data Objects — Prior to this release, Rollbase fetched
all records from the Data Object Service to count them when rendering a record list view. This release
introduces the capability for Rollbase to invoke a count operation on the Data Object Service to return the
count without fetching the records. Enabling this behavior requires the following:
• The OpenEdge Data Object Service must implement a count operation that returns the total number
of records.
• You must enable count on the object definition by checking a new property on the object definition,
Service Object supports count operation.
Programmatic client-side customization
Topics in this section explain how HTML event handlers, the Rollbase AJAX API, and the Rollbase JavaScript
API allow you to create a customized user experience and provide a set of examples. Progress recommends
that you use browser-side debugging as you develop. The JavaScript alert() method provides a simple way
to debug your client-side JavaScript as you write it. Be sure to regularly monitor your browser's JavaScript
errors. For Firefox, the FireBug plug-in can be useful for this purpose. If you do not have FireBug, you can use
the Error Console window.
Making too many AJAX calls from a UI page (for example, making them periodically with small time interval)
can seriously affect the system's performance. To prevent that, the total number of AJAX API calls is limited
per user's login session. The limit is 1000 calls by default, which, depending on your license, can be changed
in Private Cloud installations.
For detailed descriptions of the Rollbase AJAX APIs, see Client-side AJAX API on page 1032. For detailed
descriptions of the Rollbase JavaScript APIs, see Client-side JavaScript on page 1131.
Custom CSS
You can use custom CSS to modify certain aspects of the user interface for a particular application. Add the
custom CSS to either the application's custom header or to the application's custom sidebar. You can also use
custom CSS to modify the user interface for all applications in a tenant. This requires you to upload a CSS file
as a hosted file and specify the hosted file as the CSS Stylesheet on the Account settings on page 727 page.
When you add custom CSS to an application or to a tenant, you are overriding the defaults in the default
Rollbase CSS files. You can view the contents of these files to gain insight into customizations you want to
make.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 507
Chapter 7: Customizing the user experience
The main CSS file for the New UI is newui.css. There is also a CSS file for each built-in theme. The files are
in the following locations:
• Rollbase Private Cloud: http://localhost:8830/prod1/css/newui/ — For example, to view
newui.css when using a tenant running the PAS server, you would use the URL
http://localhost:8830/prod1/css/newui/newui.css.
• Hosted Rollbase: https://www.rollbase.com/prod1/css/newui/ — For example, to view
newui.css, you would use the URL https://www.rollbase.com/prod1/css/newui/newui.css.
You can also see the CSS files used on a particular page by viewing the page source in your browser.
The following are a few of the ways in which you can customize the user interface, with links to examples of
each.
Detecting mobile devices
You can trigger CSS rules based on the device by leveraging the following classes added to the html element:
• rbs-device-mobile {} — Will be present when the device is either a smartphone or a tablet
• rbs-device-smartPhone {} — Will be present when the device is a smartphone
• rbs-device-tablet {} — Will be present when the device is a tablet
See an example that uses these classes.
Detecting UI Blueprint
To customize the UI based on the application blueprint, you can apply different CSS rules by leveraging the
following existing classes present on the body element.
• rbs-ui-template-type-default (Traditional)
• rbs-ui-template-type-2 (Modern Vertical BP)
• rbs-ui-template-type-custom
See an example that uses these classes.
Changing the page title width
On view and edit pages, the page title area has two parts:
• The page title
• The page toolbar.
By default, the available page width is shared as follows:
• On medium and large devices (width is 769px or greater), the width is shared equally by both parts.
• On small devices (width is 768px or less), the page title consumes 30% of the width and the page toolbar
consumes 70% of the width.
Administrators can override these proportions at the application level to change the percentage of space
occupied by the page title to give the page toolbar more space to display actions in the toolbar rather that in
its overflow using the following CSS classes:
• .rbs-objectViewTitle — CSS class to customize the width of the page title in a record view page
• .rbs-objectEditTitle — CSS class to customize the width of the page title in a record edit page
See an example that uses these classes.
508 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Programmatic client-side customization
Controlling how space is consumed in columns
View and edit pages can contain up to four columns. You can control the space consumed within a column by
the field label, the field value, the separator between them, and, for edit pages, the editable field value. Use
the following CSS classes to control the space:
• rbs-simpleField-label-cell — Controls the space consumed by the field label
• rbs-simpleField-value-cell — Controls the space consumed by the field value
• rbs-separator-cell — Controls the space consumed by the separator between the label and the value
• rbs-editField-valueContainer — Controls the space consumed by the editable field value (edit pages only).
This is specified as a percentage of the width consumed by the field value (rbs-simpleField-value-cell).
The graphic below illustrates what each of these CSS classes control:
You specify the space consumed as a percentage of its container, except for rbs-editField-valueContainer,
which is specified as a percentage of the width consumed by the field value.
Default values for the field label, the field value, and the editable field value depend on the screen width.
You can see the column layouts by adding &demoFieldsLayout=true to the end of the URL for the page. The
screen below shows the space consumed by field labels and values on a view page:
The screen below shows the space consumed by field labels, values, and editable values on an edit page:
See an example that uses these classes.
Custom CSS examples
The following are examples using custom CSS in Rollbase. You would add this code to either a custom header
or a custom sidebar.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 509
Chapter 7: Customizing the user experience
Changing the font size
The default font size for application pages using the New UI is 12px. Administrators can change the default
font size for an application by adding a style to either a custom header or a custom sidebar. You can specify
different rules for desktop and mobile devices. The following style, if added to a custom header or custom
sidebar, results in a font size of 14px for that application on both desktop and mobile devices:
<style> /* Rule for desktop font size */
html:not(.rbs-device-mobile).rbs-mainFontSize,
html:not(.rbs-device-mobile) .rbs-mainFontSize {font-size: 14px;}
/* Rule for mobile font size */
html.rbs-device-mobile.rbs-mainFontSize, html.rbs-device-mobile .rbs-mainFontSize
{font-size:14px;}
</style>
Other page elements, such as section headers and titles, are changed proportionally to the default font. For
example, if a title was rendered at 28px for a default font size of 14px, it would be rendered at 20px for a default
font size of 10px.
Changing the page title width
To customize the width of the page title for an application, add custom styles to either the custom header or
to the custom sidebar. The following example uses the CSS @media query to change the width of the page
title to consume 20% of the screen width on view pages:
<style>
@media only screen and (min-width: 769px) {
/* Device is Small, medium, large */
.rbs-objectViewTitle,.rbs-objectViewTitle {
width: 20%; /* Rest of space will be consumed by toolbar buttons and overflow
*/
}
}
@media only screen and (max-width: 768px) {
/*Device is Extra Small */
.rbs-objectViewTitle,.rbs-objectViewTitle {
width: 20%; /* Rest of space will be consumed by toolbar buttons and overflow
*/
}
}
</style>
Controlling how space is consumed in columns
The following example uses the CSS @media query sets the space consumed by the label, the value, and the
editable value as a percentage of the screen width:
@media only screen and (max-width: 415px) {
.rbs-simpleField-label-cell { width: 40%; }
.rbs-simpleField-value-cell { width: 60%; }
.rbs-editField-valueContainer { width: 95%; } }
For information about adding code to custom headers and sidebars, see Header and footer on page 117 and
Custom sidebar on page 117.
Personalizing CSS
Rollbase provides the following features that make it easier to customize image and JSP files for white labeling:
• Customizing image files — The Rollbase installation directory now contains a folder,
<rollbase_install_dir>\pas\rollbase\personalize\images, where you can place image files
that override standard Rollbase image files. Any files in this folder will be used instead of the standard
510 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Programmatic client-side customization
images. To replace standard images, copy the image file you want to use into the above directory. The
following image files can be overridden:
• Images in the application switcher from setup pages and on the Applications Setup > Applications
page:
• web-app-this.png — For desktop browsers, the icon next to the Rollbase application (application
switcher only)
• web-app.png — For desktop browsers, the icon next to other applications (all applications on the
Applications Setup > Applications page)
• mobil-app-this.png — For mobile browsers, the icon next to the Rollbase application (application
switcher only)
• mobil-app.png — For mobile browsers, the icon next to other applications (all applications on the
Applications Setup > Applications page)
• Images on the Getting Started with Progress Rollbase page:
• 1icon.png — The icon next to Create New Apps
• 2icon.png — The icon next to Customize Your Apps
• 3icon.png — The icon next to Share Your Apps
• Images in setup page headers:
• pacific-logo.svgz — The Progress Pacific logo
• setupLogo.svgz — The Setup logo
• Images in application page headers:
• Progress.png — The Progress logo for light themes
• ProgressBlackBg.png — The Progress logo for dark themes
• Images on portal and account settings pages:
• Poweredby.gif — The Powered by Progress logo
• Customizing JSP files — References to obfuscated classes have been removed from the following JSP
files, making the migration of customizations easier. Now, when there are no changes to the original JSP
file in a new release, you can replace it with your customized file from the previous release. Any changes
to these files will be documented for each subsequent release, so you will know whether the files you have
customized need to be changed. All directories are relative to
<rollbase_install_dir>\Pas_Instance\webapps (if using PAS) or
<tomcat-install-dir>\webapps (if using Tomcat).
• router\login\loginPrivate.jsp — The custom login page
• router\login\logout.jsp — The custom logout page
• router\login\forgotPassword.jsp and router\login\forgotPassword2.jsp - The custom
forgot password page
• router\login\mobile.jsp — The custom mobile login page
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 511
Chapter 7: Customizing the user experience
• master(or prod1)\components\logout.jsp — The custom logout animation page.
• master(or prod1)\components\loginExpired.jsp — The custom login expired page
Note: Customers who customized portaltheme.css and rbtheme.css files accessible from
<WebSiteHTTP(s)>/css will now have to place the customized files under the
Rollbase_Home/personalize/css folder.
Creating Custom Themes
Rollbase includes several built-in themes that were built using Telerik Kendo UI. You can customize any of
these themes to match the look and feel of your website using the Kendo UI ThemeBuilder, a tool that lets you
modify Kendo UI themes.
Refer the Kendo UI ThemeBuilder documentation for details about modifying themes.
You can also customize built-in themes using custom CSS. When you add custom CSS to an application, you
are overriding the defaults in the default Rollbase CSS files. You can view the contents of these files to gain
insight into customizations you want to make. The CSS file location for the built-in themes are
in[Rollbase_Home]/prod1/css/newui/ . You can also see the CSS files used on a particular page by
viewing the page source in your browser.
Note:
• You can leverage a hosted File to implement a Tenant-wide theme (the hosted file is only an override since
Rollbase v4.0.0)
• You can leverage a Custom header or custom side bar to implement an App specific theme (or override
some rules from your own tenant wide custom theme)
The CSS rules are split into two files - newuiStructure.css and newui.css. The newui.css contains
the rules that you would likely want to override.The remaining is into the structure, thus providing a smaller file
to focus upon. Rollbase also provides theme specific files. Both the full newui.css as well as the theme files
are available in uncompressed format.
Use the utility function rb.newui.util.getThemeContentColors to access the current built-in theme
color. You may also use this function for a more complex scenario to dynamically change some colors on
elements.
Use the utility functionrb.newui.util.getContrastColor to compute a contrast color dynamically: The
intent is to help write scripts where one needs to compute the color dynamically and assign it using jQuery on
the fly. For example - a text color contrasted from a background color.
The new UI has the following CSS Inclusion order:
1. newuiStructure.css
2. newui.css
3. newui.<theme-name>.css
4. custom Header or custom Sidebar
512 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Programmatic client-side customization
Rollbase includes FontAwesome icons, which are scalable vector icons that can be customized for size, color,
drop shadow, and anything that can be done with CSS. See the following resources for instructions and
examples of using FontAwesome icons:
• http://fortawesome.github.io/Font-Awesome/cheatsheet/
• http://fortawesome.github.io/Font-Awesome/examples/
Perform the below steps to create a custom theme using hosted CSS files.
1. Override specific Rollbase CSS rules based on your color palette and overall design.
2. Create a Kendo UI custom theme CSS file using the Kendo UI Themebuilder.
Note: This step is optional. Perform this step only if there is a need to change the overall design of the
Kendo UI widgets. However, if the need is to override a few rules, for example the primary color, you can
simply do that as part of step 1 above.
3. Combine these into a single CSS file and attach it to your application environment as a hosted file:
• Log under the tenant/customer to which you want to apply the custom theme
Note: This is applicable to only a customer tenant.
• Under App Setting and click Hosted Files.
• Choose New Hosted File and give it a File Name (the name of your theme is recommended - you can
create multiple themes this way).
• Upload the CSS file.
4. Assign CSS file to the tenant (Customer) for applying the theme to all your applications:
• Go to Setup Home
• Select Account Settings (only available if logged under non-master tenant)
• In Appearance, for the CSS stylesheet, select the name of the style created previously
HTML event handlers
HTML events occur in a client's web browser when a user moves, clicks and drags the mouse, enters text, and
performs other interactions. HTML components, such as text boxes or picklists, can expose JavaScript handlers
to be invoked when these events occur. You can read more about HTML events at this recommended web
site: http://www.w3schools.com/js/js_events_examples.asp
Using event handlers, you can customize the behavior of your HTML components. In the example below, the
pair of handlers named onfocus and onblur for Text Areas will expand a component to eight rows when it
receives focus (onfocus) and then compress it to two rows when it loses focus (onblur):
As shown, the this reference can be used inside event handlers to access or modify the properties of the
relevant input field.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 513
Chapter 7: Customizing the user experience
Tips for writing event handling scripts:
• You cannot use form in a Page's onload script. Instead, note that the HTML form used to edit or create an
object record is always named theForm.
• A good practice is to verify that the JavaScript function you are calling exists on the current page.
• Use prefixes to avoid naming conflicts. Note that Rollbase JavaScript system functions have the prefix rbf_
and system variables have the prefix rbv_.
• Keep in mind that disabled HTML controls do not send values upon HTML form submit.
• It is important to use the integration code of the selected picklist option rather than the field itself in formulas.
That field is replaced with a system-generated ID that is different from installation to installation, so you
cannot rely on it in formulas when publishing your application.
Defining event handlers
Rollbase provides a way to specify JavaScript handlers for HTML events. To access this feature, navigate to
an object's definition page (from the application switcher, navigate to Setup Home Application Setup >
Objects and click the object) Scroll down to the Fields section and click the Events link in the Action column
for a particular field.
Alternatively, you can navigate to the Field View page and select Event Handlers from the More Actions
drop-down menu.
Different field types expose different event handlers. For instance, a text input box exposes the following:
onchange, onclick, onfocus, onblur, onkeypress, onkeydown, onkeyup, onselect, onmousedown,
onmouseup, onmouseover, onmouseout. A picklist exposes the following: onchange, onclick, onfocus,
onblur, onmouseover, onmouseout. Read-only and hidden fields do not expose any handlers.
514 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Programmatic client-side customization
The following screen shows an example screen that defines event handling code for an email address:
The Event Handlers Helper allows you to select names of other object fields and values or integration codes
for picklists and lookups. Select a field from the drop-down menu. The value to use in JavaScript displays in
the center field. Note that, unlike similar helper components for templates, these helper tokens contain just the
fields' integration names rather than template tokens. These names can be used to refer to HTML elements
in client-side JavaScript.
To view how your event handling code appears in generated HTML at runtime, click Debug to open the debug
window. This window displays the actual field's HTML and renders the component below.
Before testing HTML event handlers, turn on notifications about JavaScript errors in your browser. Note that
generated HTML event-handling code will be enclosed in double quotes, as shown in the onfocus method
above. If you need to use a double quote inside your code, precede it with a backslash instead, such or consider
using a single quote.
Try to keep your event handler code relatively short. For longer handlers, you can call JavaScript functions
inside custom script components in your page(s).
You can use this in the body of event handlers to refer to the field and its properties. You can also pass this
as parameter to any custom JavaScript functions that need to work with this field.
Event handling code is stored per field. Once specified, event handling code will be used for all new, edit, and
status changes pages.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 515
Chapter 7: Customizing the user experience
Copying a field's value to other fields
In some cases, you may need to use a value entered into one field as the default value for another field. For
example, an email address is likely to be reused as a login name. To achieve this, you can implement the
onblur handler for the email field. Enter the following JavaScript code:
if (form.loginName && form.loginName.value=='') form.loginName.value=this.value;
This code first verifies that the loginName field exists in the current form and has no value specified by the
user.
You can use the prefix form in front of any field integration name to reference that field in the DOM. For
example, in the above code we reference the loginName field as form.loginName.
Disabling fields
Often, behavior of one field should depend on a selection made in another field. Consider the example below,
in which there are three fields:
• Club Member (checkbox)
• Membership Fee (currency)
• Member Since (date)
The last two fields should only be available for the user to enter data if Club Member is checked.
The steps below describe how to accomplish this:
1. Create a script component on the page with the following code:
<script>
function my_showClubControls(form) {
var isMember = form.club_member.checked;
rbf_setFieldDisabled('membership_fee', !isMember);
rbf_setFieldDisabled('member_since', !isMember);
}
</script>
2. Add event handling code to the onclick event of the Club Member check box (you can pass form as a
parameter to JavaScript functions):
if (typeof my_showClubControls == 'function') my_showClubControls(form);
3. For consistency, add the same code as above to the page's onload handler:
if (typeof my_showClubControls == 'function') my_showClubControls(document.theForm);
516 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Programmatic client-side customization
The Membership Fee and Member Since fields will be enabled or disabled, depending whether the check
box Club Member is checked.
Setting default values
In some cases, the selection or input of a certain value in your form should determine the default value for
another field. Consider an extension of the example described in Disabling fields on page 516, in which a
selection in a picklist named Membership Type determines the default value for another field named
Membership Fee.
Follow these steps to create the logic that sets the value of a field based on the user's selection in another
field:
1. Create a picklist named Membership Type with three values. Each of the values must have an integration
code as shown below:
2. Add a script component to the page:
<script>
function cust_membFee() {
with (document.theForm) {
var code = membership_type.options[
membership_type.selectedIndex].getAttribute('code');
if (code=='A')
membership_fee.value=1000;
else if (code=='C')
membership_fee.value=500;
else if (code=='S')
membership_fee.value=200;
else
membership_fee.value='';
}
}
</script>
3. Add the following code to the onchange event handling code for the Membership Type picklist:
if (typeof cust_membFee == 'function') cust_membFee();
Now, when the Membership Type option is selected and the Membership Fee box is empty, this box will
be prepopulated with a new value depending on the selection.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 517
Chapter 7: Customizing the user experience
Using system settings to define values that might change
The example shown in Setting default values on page 517 embeds values directly into JavaScript code. This
makes it difficult to maintain values that might change over time. It is often the case that a better solution can
be achieved by using system-wide settings.
System-wide settings are available from the Administration Setup area. You can create fields for the Settings
object as you do for any other object definition. The difference is that only one Settings record exists per tenant.
Values from that record can be used in various templates, formulas, etc.
To use system settings, let's make some changes to the example shown in Setting default values on page 517:
1. From the application switcher, select Setup Home.
2. Click Settings under Administration Setup
3. Click Configure:
The object definition page for Settings opens.
518 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Programmatic client-side customization
4. Create three Currency fields for the Settings object: Admiral Fee, Captain Fee, and Sailor Fee. Set a default
value for each of these fields (default values can be changed later). See Adding fields on page 134 for
information about adding fields to an object definition.
5. Modify the above script to use values from the Settings record instead of hard-coded values as shown
below:
<script>
function cust_membFee() {
with (document.theForm) {
if (membership_fee.value=='') {
var code = membership_type.options[
membership_type.selectedIndex].getAttribute('code');
if (code=='A')
membership_fee.value='{!#SETTINGS.admiral_fee}';
else if (code=='C')
membership_fee.value='{!#SETTINGS.captain_fee}';
else
membership_fee.value='{!#SETTINGS.sailor_fee}';
}
}
}
</script>
Rollbase AJAX APIs
HTML event handlers are very useful for assisting in the creation or editing of Rollbase records. However, to
fully use the power of HTML event handling, you might need to retrieve data from other Rollbase records or
update other records from within custom client-side code. This can be achieved by using the Rollbase AJAX
API. Any JavaScript on a Rollbase page can call these APIs as JavaScript functions.
The Rollbase AJAX API uses the same access control rules as the Rollbase user interface and the SOAP API.
A currently logged-in user must have valid permissions to view or edit the requested object record.
See Client-side AJAX API on page 1032 for the available AJAX APIs. Progress is continually extending the list
of available APIs.
Using the AJAX API to make frequent calls to the production server can seriously slow the system, especially
if many users are online simultaneously. To prevent that from happening Rollbase limits the total number of
AJAX calls per user login session to 1000. Private Cloud customers can alter that limit.
Examples
The examples in this section demonstrate use of Rollbase AJAX APIs.
To access and customize Kendo UI widgets refer - https://docs.telerik.com/kendo-ui/api/javascript/ui/alert.
This provides a common interface to work against different field types, to:
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 519
Chapter 7: Customizing the user experience
• Get/set field value
• Get Kendo Configuration i.e. getKendoConfig(). Irrespective of whether it is kendoDataPicker or
kendoNumericTextBox etc. Kendo way is jqueryObj.data(‘kendoDatePciker’) &
jqueryObj.data(‘kendoNumericTextBox’)
• Enable or disable a field
• Show/Hide a field
• Access field JSON data used to render the field
• Access the JQuery object for the field. (instead of running a JQuery selector against DOM which will have
performance overhead)
Showing or hiding a page section
You can show and hide sections on an Edit page based on a user's selection. This example was contributed
by Tim Colson.
The example use case:
• The object has a picklist with the values Not a member (code NO) and Club member (code YES)
• The page's Membership Info section should be shown if Club member is selected and hidden otherwise.
To accomplish this, follow these steps:
1. In the page editor, add a script component with the following script to the Edit page (see Editing pages on
page 369):
function customizeEdit() {
var sectionID = rbf_getSectionIdByTitle("Membership Info");
var code = rbf_getPicklistCode("membership");
rbf_showOrHideSection(sectionID , code=="YES");
}
2. Add onchange event handler to the picklist: customizeEdit();
3. For consistency, add an onload event handler to the page: customizeEdit();
When the section is hidden, it looks like this:
When the section is shown, it looks like this:
520 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Programmatic client-side customization
A simple lookup
Consider the following example: A Rollbase page includes a lookup field (see Relationships between objects
on page 148) for a property and an amount for a proposed mortgage. Upon selection of the property, we want
to use the property's value as the default for the mortgage amount. This means a server-side trip using the
AJAX API, as illustrated below.
To implement this example, follow these steps:
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 521
Chapter 7: Customizing the user experience
1. Create the objects Property and Mortgage, with a one-to-many relationship between Property and Mortgage
(one property can have more than one mortgage)
2. For the Property lookup field in the Mortgage object definition, implement the following onchange event
handler:
if (typeof cust_populateAmount=='function')
cust_populateAmount();
3. Add the following script component to the New Mortgage page using the page editor:
<script>
function cust_populateAmount() {
var propId = document.theForm.R4388623.value;
rbf_getFields("property1", propId, "appraisal_amount",
cust_callbackAmount);
}
function cust_callbackAmount(objName, id, dataValues) {
if (document.theForm.amount.value == '')
rbf_setFieldValue('amount',dataValues.appraisal_amount);
}
</script>
Now, when the Property lookup field is updated, it triggers an AJAX call to Rollbase and assuming that the
requested record exists and the user has appropriate access rights, the value of the appraisal_amount field
will be set as the default to the amount field.
A financial calculation
While formulas provide a powerful way to display calculations on View pages, they are not so useful on Edit
pages, since formulas cannot dynamically use changes made by a user while entering data into a form. However,
formulas can be used on Edit and New pages as placeholders for dynamically calculated values, even though
the actual calculations now have to be performed on the client side using HTML events and the JavaScript
API.
Consider the example of an object that has three fields:
• A Currency field named Amount with the integration name amount
• A Percent field named Rate with the integration name rate
• A Formula field (with a return type of Currency) named Interest with the integration name interest and the
formula body {!amount}*{!rate}/100
The View page looks like this:
You can add these same fields to the Edit page:
522 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Programmatic client-side customization
However, when the user changes the content of the two editable fields (Rate and Amount), the content of the
formula field does not change. To have the field change, you need to add a financial calculation similar to the
following:
1. Add a script component to the Edit and New pages (see Editing pages on page 369):
function cust_interest() {
var m = rbf_getFloat(rbf_getFieldValue("amount"));
var r = rbf_getFloat(rbf_getFieldValue("rate"));
var interest = m*r/100;
rbf_setFieldContent("interest",
rbf_formatCurrency(interest));
}
2. Add onchange handlers to the amount and rate fields:
if (typeof cust_interest == 'function') cust_interest();
3. Add the same code to the onload script on the Edit page for consistency.
Now the content of the Interest field will be dynamically updated on the Edit and New pages in a consistent
manner with the View page.
Avoiding mixing client-side and server-side APIs
When working with client-side and server-side APIs, you must clearly understand the difference between the
two API definitions to avoid using client-side APIs for server-side APIs, or vice-versa. All server-side APIs are
prefixed with rbv_api. and all client-side APIs are prefixed with rbf_. Unlike client-side APIs, server-side
APIs cannot be executed in the Web browser directly. If you must execute a server-side API in a client-side
script, you must enclose the server-side API in an #EVAL[ ] block. The following section describes, with
examples, how to avoid mixing client-side and server-side APIs.
The following script, when added to a page's script component, will cause a runtime error because an rbv_api.
variable (a server-side API) is not recognized by a Web browser’s script:
<h2>Number of Clients: <span id='counter'></span></h2>
<script>
var count = rbv_api.selectNumber("select count(1) from client");
document.getElementById("counter").innerHTML = count;
</script>
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 523
Chapter 7: Customizing the user experience
The two ways to fix the above error are:
• Enclose the server-side API in an #EVAL[ ] block:
<h2>Number of Clients: <span id='counter'></span></h2>
<script>
var count = #EVAL[ rbv_api.selectNumber("select count(1) from client"); ];
document.getElementById("counter").innerHTML = count;
</script>
Note: When working with Script components, you can use the Test EVAL[] Block button to debug/develop
server-side script.
• Use a client-side API instead of a server-side API:
<h2>Number of A: <span id='counter'></span></h2>
<script>
rbf_selectNumber("select count(1) from a", function(value) {
document.getElementById("counter").innerHTML = value;
});
</script>
Typically, server-side API execution is faster and it is not subjected to a limit on the number of AJAX calls
allowed per login session. A client-side API is used whenever user input can only be made available during
runtime and not when the Web browser page is rendered.
Access control
Since the client-side API gives users (or portal users) access to underlying data, functions that access and
modify the data are subjected to access permissions. If the current user does not have sufficient permissions,
the API call will fail.
See Security and access control on page 643 for more information about access control and permissions.
See Client-side AJAX API on page 1032 for the available APIs and permissions required for each.
Rollbase portals
Portals are essentially external-facing web applications built using the same components as standard Rollbase
applications. Portals typically run on a corporate website or intranet. You can create portal pages to display
dynamic lists of records, to allow creation of records through custom forms, and to invoke triggers and custom
business logic.
For a video tour of creating a portal, see "Creating a Public Web Portal for a Progress Rollbase Application"
.
You can create any number of portals for an application and publish them as a part of the application XML.
For information on publishing applications, see Publishing and distributing applications on page 691.
Portals are different from normal Rollbase applications in three significant ways:
• Portals can be accessed by anyone with internet access, although a portal can require users to register
and/or log in. See Portal security on page 540 for more information.
• Portals do not run within the normal Rollbase environment, which typically displays application objects in a
tabbed interface. Instead, they consist of a set of pages that are linked together to form a cohesive website.
524 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Rollbase portals
• Portals can adopt the look and feel of any existing website in which they are embedded. See Creating a
custom header and footer on page 537 for more information.
The following graphic illustrates the differences between Rollbase application and portal usage:
Portal visitors
A portal can allow authenticated or non-authenticated visitors:
• Portals for authenticated visitors include a login page. When you create a Login Form portal page, you
select which type of user account to support. Each Login Form only accepts logins from one type of user
account:
• Users - accounts created for your tenant as Rollbase User records.
• Rollbase object records - accounts created for objects with the Portal User attribute. This allows users
who do not have Rollbase accounts to use a portal as authenticated portal visitors. For more information
about this type of user account, see Creating a portal user on page 541.
• Portals for non-authenticated visitors do not include a login page.
Because portal users cannot select their own language, date format, and time zone the way regular users do,
portal-level settings apply to all portal visitors.
For more information about portal visitors and accounts, see Portal security on page 540.
Planning and building portals
In addition to portal-level settings, a portal consists of a set of portal pages interconnected by links in any order
you prefer. Portal pages can be shared among different portals in your tenant. When you create a new page
from a portal's view page, the new page is automatically assigned to the selected portal. Later, you can share
that page with other portals. See Assigning pages to a portal on page 540 for more information.
Portals give you greater flexibility than is available with normal Rollbase application pages. However, developing
a portal also carries a greater responsibility, so planning your portal strategy in advance is important. It is often
a good idea to start with a diagram that shows how visitors can navigate through the portal pages you intend
to create.
For example, the following diagram shows a simple portal that searches for and displays records:
This portal does not require a visitor to log in. See Creating portals without authentication on page 543 for more
details about developing this portal.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 525
Chapter 7: Customizing the user experience
You also need to identify the type of user(s) who can access the portal, determine the types of records they
can access, and specify the appropriate permissions. Setting permissions for portals requires careful planning
to ensure that portal users can access information they are supposed to access and that they cannot access
information they are not supposed to access. Even portals without authentication require setting permissions.
See Creating portals without authentication on page 543 and Creating portals with authentication on page 544
for examples.
Building a sophisticated and easy-to-use portal often requires significant knowledge of web design, HTML,
CSS, and JavaScript.
Steps to create a portal
Follow these steps to create a portal for a Rollbase application:
1. Create the portal.
2. Modify the portal's initial page. Rollbase creates this page when you create the portal.
3. Add other pages to the portal. Portal pages can be shared between different portals.
4. Optionally create a custom header and footer for the portal.
5. Configure portal security.
The following topics describe these steps in detail:
• Creating a portal on page 526
• Creating portal pages on page 528
• Creating a custom header and footer on page 537
• Portal security on page 540
Creating a portal
Follow these steps to create a portal:
1. From the Setup Application page for your application, select Portals from the ribbon.
The page scrolls to the Portals section:
2. Click New Portal.
The New Portal page opens:
526 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Rollbase portals
3. Enter the following information:
• Portal Name: Give the portal a descriptive name.
• Is Deployed: Exposes the portal to external access; keep this box unchecked until the portal is ready
to use.
• Field-Level Help: If checked, a ? icon displays next to fields and contains any field-level help you have
defined.
• "Powered by" Logo: Check this box to include a Powered by Rollbase logo at the bottom of portal
pages.
• AJAX Calls for non-authenticated portal users: If this box is checked, AJAX calls will be allowed to
this portal without authentication. Depending on where and how the portal is deployed, this can be a
security risk. Use this option carefully.
• AJAX Calls for authenticated portal users: If this box is checked, AJAX calls will be allowed to this
portal with authentication.
• Bootstrap Version: Select a bootstrap version to be used during runtime of a portal page. Only users
who have an administrator role have the permission to make a selection.
Note:
• By default, when you create a new portal, Bootstrap version v4.0.0 is selected.
• If an existing portal had the Use Bootstrap v3 option checked, the bootstrap version v3.3.7 will be
automatically applied to retain the selection.
• If an existing portal had the Use Bootstrap v3 option unchecked, the bootstrap version v2.3.1 will
be applied.
• When you export or import an application the bootstrap version selected for a portal is retained.
• When you select a bootstrap version (3 or above) and opt to use CDN, the bootstrap files are loaded
from CDN.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 527
Chapter 7: Customizing the user experience
• Include Kendo UI: If this box is checked, Rollbase will add Kendo UI-related CSS and JS files for the
portal. If you only want to use a few Kendo UI features, leave this box unchecked and include only the
files required for those features. This will result in a lighter page that loads faster. For example, currently
the entire Kendo UI library is 2,594KB and the two color picker JS files total 33KB. See
http://www.telerik.com/kendo-ui for more information.
• Right to Left Text Direction: If this box is checked, Rollbase will use right-to-left text direction. This is
intended for portals that use a language written from right to left, such as Arabic or Hebrew. This is an
experimental feature.
• Language: Select the language for the portal pages.
• Date Format: Select the date format to use in this portal in display and input fields.
• Time Zone: Select the time zone for this portal. All date/time field values will be adjusted to this time
zone.
• Description: Provide a description for this portal.
• Login URL: Use this setting only for portals embedded into other websites that require authentication.
This is the URL for logging into the portal.
• Add to Applications: Select the applications to which this portal will be added.
4. Click Save.
Rollbase creates the portal and a new, empty generic page that is the default main portal page. Depending
on your requirements, you can edit this page to add content to it, or you can assign a different main page
to the portal and delete this page.
5. Create portal pages for the portal.
6. If you are planning to use a portal as part of your website--rather than embedding it in one of your website's
pages using an HTML iframe--configure the header and footer to adopt the look and feel of your site. See
Creating a custom header and footer on page 537 for more information.
7. Configure Portal security on page 540.
Creating portal pages
To add a page to a portal:
1. On the portal's view page, click New Page.
The New Portal Page page opens.
2. Check Only logged in portal users can access this page if you only want authenticated (logged-in) portal
visitors to access this page.
3. Select a page type:
• Generic Page - A page in which you can embed list views (list of records of a specific object type) and
arbitrary web content, such as HTML or JavaScript. A new page is initially empty.
• Search Results Page - A page used to display the results of a search within a portal. A new page
contains a list of objects.
• Object View Page - A page to view a single record of a specific object type. A new page is initially empty.
• Object Create Page - A page to create a single record of a specific object type. A new page contains
a submission form.
528 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Rollbase portals
• Object Edit Page - A page to edit a single record of a specific object type. A new page contains a
submission form.
• Object Selector Page - A page in a popup window that is used to select related records when using a
lookup field in an Object Create or Object Edit page. A new page contains a list of objects.
• Login Form - A page specifically designed to allow portal users (Rollbase users and records with the
Portal User attribute) to log in to a portal. A new page contains a login form with a user name and
password.
• See Portal security on page 540 for more information about portal users.
• Take Survey - A page where portal visitors can answer survey questions. You can only create a Take
Survey page if the application for which you are creating the portal contains at least one object with the
Survey attribute. A new page contains a list of survey answers. You must configure a Take Survey
page to specify the survey record to use. See Portal page actions on page 535 for instructions. Portal
visitors must log in to the portal to take a survey.
• See Using surveys on portals on page 359 for more information.
4. From the Object Type drop-down list, select the type of object to which this page should be associated:
• For a Login Form, the list includes existing Rollbase users and objects with the Portal User attribute;
you are creating a login page for a specific type of portal user.
• For a Take Survey page, the list includes objects that have the Survey Taker attribute.
• For any page type other than Generic Page, Login Form, or Take Survey, the list includes all available
objects.
5. Click Save.
After creating a portal page, you can modify it so its behavior meets your requirements.
Modifying a portal page includes:
• Editing the page
• Modifying portal page properties
Editing portal pages
When you create a portal page, you can edit it to define or modify its content. You edit pages in the portal page
editor. The portal page editor opens when you create a new page.
To edit an existing portal page, do one of the following:
• From the portal view, click Edit in the table of pages next to the page you want to edit.
• From the portal page view, click Edit.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 529
Chapter 7: Customizing the user experience
The portal page editor opens:
Editing a portal page is similar to editing an application page. See Editing pages on page 369 for more information.
On the portal page editor, you can:
• Drag a new section from the left column onto the page.
• Drag an HTML component onto the page. See Adding an HTML component to a page on page 187 for more
information.
• Drag a script component onto the page. See Adding a script component to a page on page 187 for more
information. The script component can be an EVAL block; see Adding an EVAL block to a portal page on
page 531 for an example.
• Drag any of the components under Available Components onto the page. The available components vary
depending on the page type and the object with which the page is associated, if any.
• In the above graphic, an Object View page is associated with the Title object. The page displays a Title
and a link to the All Titles portal page.
• Add search forms. Pages with search forms require further configuration; see Portal page actions on page
535 for details.
530 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Rollbase portals
• Specify properties for page components. For example, you can specify which view to use to display a list
of objects. The graphic below shows the possible views that can be used to display a list of Titles.
Adding an EVAL block to a portal page
You can add an #EVAL[ ] block to a portal page to add JavaScript-based extensions to the page. You can
use an #EVAL[ ] block when you want to use JavaScript expressions to generate HTML. An #EVAL[ ] block
returns a String. You can use server-side Rollbase APIs in an #EVAL[ ] block. See Using EVAL blocks on
page 198 for more information about #EVAL[ ] blocks. See Server-side API on page 949 for more information
about server-side Rollbase APIs.
To add an #EVAL[ ] block to a page:
1. Open the page editor in one of the following ways:
• From the portal view, click Edit in the page table next to the page you want to edit.
• From the portal page view, click Edit.
The page editor opens.
2. Drag New Script Component from the left column to the location where you want to add the #EVAL[ ]
block.
A new <Script Component> appears in the page. The component can be in its own section or can be
added to an existing section, depending on the page type and existing content. In the following graphic, the
component is added to the default section of a generic page:
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 531
Chapter 7: Customizing the user experience
3. Click Edit in the <Script Component>.
The Edit Script dialog opens:
4. Add the JavaScript #EVAL[ ] block to the text area. You can use the Template Helper to generate tokens
for IDs, URLs, and links you want to use in the block.
5. When you are finished adding the #EVAL[ ] block, click Save in the Edit Script dialog and click Save in
the page editor.
The following #EVAL[ ] block:
532 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Rollbase portals
• Defines a function f1().
• The function uses the server-side query API to execute a SELECT query that returns the id, name,
and author fields from Title records.
• The function then loops through the query results and generates a buffer containing an HTML table
that displays the title and author of each Title record.
• Each displayed title links to the portal's Object View page that displays information about a single
title. The link uses tokens for the portal, the portal's Object View page, and the current Title record
ID.
• The function returns the resulting HTML.
• Finally, the #EVAL[ ] block calls the function.
#EVAL[
function f1() {
var arr = rbv_api.selectQuery("SELECT id,name,author FROM title_lb", 1000);
var buff = '<table cellpadding=5><tr><th>Title</th><th>Author</th></tr>\n';
for (var k=0; k<arr.length; k++)
buff += '<tr><td>
<a href="portal.jsp?c={!#CURR_CUSTM.id}
&p={!#PORTAL.125233463.#id}&g={!#PORTAL.125233463.127055194#id}
&id='+arr[k][0]+'">'
+arr[k][1]+'</a></td>'+'<td>'+arr[k][2]+'</td></tr>\n';
buff += '</table>\n';
return buff;
}
f1();
]
The resulting portal page looks like the following:
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 533
Chapter 7: Customizing the user experience
Portal page properties
You can view and edit portal page properties on the Page Properties page.
To open the Page Properties page for a portal page, do one of the following:
• From the portal view, in the table of portal pages, click Properties in the row of the page you want to view
or edit.
• From the portal page view, select Properties from the More actions drop-down menu.
The Page Properties page allows you set the following properties for the selected page:
Property Description Page Type
Page Name Human-readable page name All
Only logged in portal users can Portal user must be authenticated; All except Login Form
access this page otherwise, the user is redirected to
this portal's Login page.
Destination Page Page to which to redirect visitor Object Create, Object Edit, Login
after form submission Form, Take Survey
534 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Rollbase portals
Property Description Page Type
Automatically redirect to Self-explanatory Login Form
destination page when visitor
already logged in
onload JavaScript code to be invoked by All
the DOM onload event
onunload JavaScript code to be invoked by All
the DOM onunload event
Portal page actions
When viewing a portal, the pages for that portal are listed in a table at the bottom of the page. The Action
column in the table presents the following choices:
• View - Preview the selected page in a pop-up window. For Object View and Object Edit pages, you are
prompted to select an existing record.
• Edit - Edit the selected page in the page editor.
• Clone - Clone the selected page and edit the new page in the page editor.
• Del - Delete the selected page (not available for the current main portal page).
• Copy To - Clone the selected page and assign it to a different portal.
• Properties - Opens the selected page's Page Properties page; available properties vary depending on
the page's type. See Portal page properties on page 534 for more information.
• Config - Configure options for specific types of pages and page content:
• For a Take Survey page, to specify the survey record to use and the number of columns on the page.
• For a page containing a search component (Detailed Search or Search Form), to specify the object
type to search, the search results page, the field(s) to search, and the search criteria (starts with,
contains, etc.).
Generating portal page URLs
Templates used on portal pages sometimes use URLs to other portal pages. To simplify portal development,
Rollbase provides template helpers, which, for each page, can generate a token that represents:
• The page's URL
• A link to the page
• The page's ID
To generate a portal page's URL using the template helper:
1. Open the Page Properties page by doing one of the following:
• From the portal view, in the table of portal pages, click Properties in the row of the page you want to
view or edit.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 535
Chapter 7: Customizing the user experience
• From the portal page view, select Properties from the More actions drop-down menu.
The Page Properties page opens. The HTML Events Handlers section of this page includes the Template
Helper:
2. From the first drop-down field (Title in the above graphic), select the portal for which you want to create the
page's URL:
3. From the next drop-down field, select pageName[URL]:
536 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Rollbase portals
The Template Helper displays the token to use for the page's URL:
For Generic or List pages, you can use this token directly in user interface templates.
For a View or Edit page, which displays a single record, you must add the ID of the record being edited or
viewed. To do so, append the URL's id parameter to the token:
{!#PORTAL.125233463.125233479#url}&id={!id}
At runtime, the token resolves to the page's URL.
You can also use URL tokens pointing to portal pages in email templates.
Creating a custom header and footer
If you are planning to use a portal as part of your website--rather than embedding it in one of your website's
pages using an HTML iframe-- you can add a custom header and footer to your portal by adding HTML code.
The header and footer will appear in all of the portal's pages. This allows your portal to adopt the look and feel
of the website in which it is incorporated.
Follow these steps to create a custom header and footer for a portal:
1. Develop or obtain the HTML code for the header and footer. If you do not already have HTML code to use
for the header and footer, the easiest way to get started is to select a page on your website to use as a
template. View the HTML source of this page and remove any central content where you would like your
portal content to appear. All HTML code above this content should be used as the header and all HTML
code below should be used as the footer.
2. If any code in your portal header or footer HTML contains references to external files such as images,
JavaScript files, CSS files, or links to other pages using relative URLs (such as "../images/myimage.gif",
"../index.html", etc.), do one of the following:
• Switch to fully qualified URLs, including the full path to each external file. For example, you would change
"../index.html" to "http://www.mycompany.com/index.html".
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 537
Chapter 7: Customizing the user experience
• Include the following element in the <head> element of your header: <base
href="www.mycompany.com"> …, where mycompany.com is your website's URL (the full path to
the directory where your content can be found if the relative URLs were added to the end of it). The
base element tells any relative URLs to use the specified path as the root and is the only way relative
URLs will resolve to the correct domain.
3. If you have enabled the HTTPS setting for the portal, verify that your HTML code either uses a base URL
with HTTPS support or that all of the images and files referenced in the header and footer use fully qualified
HTTPS URLs.
4. When your header and footer HTML is ready to add to the portal, from the portal's view page, select Header
and Footer from the More actions drop-down menu:
The Header And Footer page opens:
538 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Rollbase portals
5. On the Header And Footer page, paste the HTML for your header into the HTML Header area.
6. Paste the HTML for your footer into the HTML Footer area.
7. You can choose to include the default stylesheet named portaltheme.css above the header in each
portal page. From the Include Stylesheet drop-down list, select portaltheme.css to include the default
portal stylesheet or select None if you do not want to use the default stylesheet.
8. If desired, you can customize the header and footer using merge fields, such as
{!#CURR_USER.firstName} in the HTML code for the header and footer. If you want to include merge
fields, use the Template Helper to create the code for each merge field. In the graphic below, the user has
selected the current portal users's name to generate the merge field to include in the header or footer:
For more information about merge fields, see Adding business logic on page 183.
9. Click Save.
Your portal pages will now contain the custom header and footer you created.
Changing the main portal page
A portal's main page is the first page to display when a visitor accesses the portal. By default, the main page
is the page automatically created when you create the portal. Its name is Main Page [portal name]. You
can change the main portal page to be a different page.
To change the main portal page:
1. On the portal view, click Edit.
2. From the Main Page drop-down list, select the page you want to be the new main page:
3. Click Save.
The page you selected is now the main portal page.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 539
Chapter 7: Customizing the user experience
Assigning pages to a portal
Portal pages can be shared among different portals in your tenant. If you want to add an existing page to your
portal, follow these steps:
1. On the portal's view page, in the Pages table, click Assign Pages.
The Assign Pages page opens:
2. Select the page(s) you want to add to your portal from the Available Pages column and click to move
the page(s) the Selected Pages column.
3. Click Save.
The pages you selected are now assigned to the portal.
Note: You can also remove pages from your portal by selecting them from the Selected Pages column and
clicking to move them to the Available Pages column.
Portal security
Portals have several facets of security:
• Protocol: Rollbase portals use the HTTPS protocol.
• Authentication: A portal can allow authenticated or non-authenticated visitors. Authenticated visitors must
log in to the portal using a Login Form. You can develop a portal that allows non-authenticated visitors to
some pages and restricts other pages to authenticated visitors. You limit access to a specific portal page
to authenticated visitors by selecting the Only logged in portal users can access this page check box in
the portal page's properties. There are two types of user accounts that can log in to a portal:
540 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Rollbase portals
• Users - accounts created for your tenant as Rollbase User records.
• Rollbase object records - accounts created for objects with the Portal User attribute. For example, you
might create an Employee object and add the Portal User attribute to it. The Portal User attribute adds
User Name and Password fields to the object. Users whose accounts are based on records of the
Employee object type can login to a portal whose Login Form page specifies the Employee object.
This allows users who do not have Rollbase accounts to use a portal as authenticated portal visitors.
See Creating a portal user on page 541 for details on creating this type of user account.
Each Login Form is configured to allow only one type of user account to log in.
• Password requirements: You can set rules for password authentication can be set when you edit a Password
field on an object with the Portal User attribute. This includes:
• The minimum length of the password.
• Whether the password must include both letters and digits.
• Access control: Access rights for portal users are set for user accounts in the following ways:
• For accounts based on Rollbase User records, access rights are specified for that user's role.
• For accounts created for objects with the Portal User attribute, access rights are specified for the Portal
User role. These permissions cannot be relationship-based and they cannot include
Location/Department/Function (LDF) filters.
• Access rights for records created by portal users are set for the Record Creator pseudo-role. See The
Record Creator role on page 664 for information about the Record Creator role.
• As an additional security measure, you can specify a whitelist of IP addresses to be checked when a portal
user logs in. For information about the additional security setup and administration, see Advanced setup
and administration on page 713.
The login session for portal user expires after a certain period of inactivity. Rollbase Private Cloud customers
can configure this time interval. See Shared Properties on page 786 for more information.
Administrators can login into a portal as a selected visitor from the portal view page by clicking the login form
page name under Login As in the More actions drop-down.
Setting permissions for portal user objects requires careful planning to ensure that portal users cannot access
information they are not supposed to access. See Creating portals with authentication on page 544 for examples.
Creating a portal user
As described in Portal security on page 540, one type of authenticated portal visitor is an account created for
an object with the Portal User attribute. Accounts created this way have the Portal User system role. If you
want users who do not have Rollbase user accounts to be able to log in to your portal, you must create an
object representing their accounts. This type of portal user can access portals that allow its specific object type
to log in, but cannot access Rollbase applications.
To create a portal user:
1. Create a new object definition and a tab for that object in your application, selecting the Contact attribute
from the Attribute table and the Portal User attribute from the Advanced Attribute table. See Creating a
new object definition on page 129 for details about creating an object definition.
2. Edit the object's New page to add the Login Name and Password fields to it. See Editing pages on page
369 for details about adding fields to a page.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 541
Chapter 7: Customizing the user experience
3. Edit the object's Edit page to add the Login Name and Password fields to it. See Editing pages on page
369 for details about adding fields to a page.
4. Launch your application and select New <object> from the object's page menu. In the following graphic,
the new object definition is named PortalVisitor:
5. Create records for the new object definition, specifying the Login Name and Password fields. These fields
are the credentials for each portal user account. Create a record for each person who will be a portal user.
When you create a Login Form portal page, you can specify the object. In the following graphic, only user
accounts based on PortalVisitor records can log in to the portal:
542 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Rollbase portals
Creating portals without authentication
Consider the following simple portal example, where a portal user can:
• Search a list of book titles.
• View a list of search results.
• View information on a selected title.
The following diagram shows the required portal pages and navigation among them:
To create this simple but fully functional portal, take the following steps:
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 543
Chapter 7: Customizing the user experience
1. Create a new portal as described in previous sections. This generates the main page.
2. Edit the main page and add a Detailed Search component to it. This is automatically available in the
Available Components section of the page editor. Add an HTML component with a welcome message.
3. Create a Search Results page for the Title object. Rollbase automatically places a list of Title records onto
this page.
4. Configure the main page to search for Title records. See Portal page actions on page 535 for more information.
5. Create an Object View page for the Title object.
6. Edit the Object View page and add and arrange fields as desired. See Editing portal pages on page 529 for
more information.
7. Edit the Object View page to add links to the Search Results page and the main page. Links to these
pages are automatically available in the Available Components section of the page editor; edit each link
to change the text as desired. See Editing portal pages on page 529 for more information.
8. Finally, add View permission to the Title object for the Portal Guest role. Unless the proper permissions
are assigned to the Portal Guest role, visitors your portal will not be able to view records.
Creating portals with authentication
When you create a portal requiring authentication, you must include a Login Form portal page to allow users
to log in. There are two types of user accounts:
• Registered Rollbase users with a Progress ID
• Objects with the Portal User attribute.
A single Login Form only allows one type of user account to log in.
The following examples illustrate two use cases for creating portals with authentication.
Example 1
Consider the following example:
You want to use a Rollbase portal to allow non-Rollbase users to respond to an invitation to an event. Each
invited person can log in to the portal and indicate whether they will attend the event.
To build such a portal, create the following:
• An object named Invitee with the Portal User and Contact attributes. See Creating a portal user on page
541 for details about creating this type of user account.
• A Radio Button field in the Invitee object named Will Attend with the values Yes and No.
• A record of the Invitee type for each person to invite, including the Login Name and Password fields.
• On the Invitee object, set the Portal User permissions to View and Edit.
The next step is to create a portal and portal pages. The following graphic illustrates the required portal pages
and the typical navigation between them:
Add the following portal pages to the portal:
544 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Rollbase portals
Page Object Page Type Description
Main None Generic Links to the Login page
Login page Invitee Login Form Allows a registered invitee to log in to the portal; destination page is
Invitation Response page
Invitation Response page Invitee Object Edit Allows a logged-in invitee to select a Yes or No button and submit t
response
Now, each invitee can log in to the portal and submit a response to the invitation.
Example 2
Consider the following, more complex example, where a portal user can:
• Register for access to a portal.
• Log in to that portal through a login form.
• View his/her information.
• Create comments.
• View the list of his/her own comments (but not comments created by other visitors).
To build such a portal, create the following:
• An object named Visitor with the Portal User and Contact attributes. See Creating a portal user on page
541 for details about creating this type of user account.
• An object named Comment with a Text Area field.
• A one-to-many relationship between Visitor and Comment.
The next step is to create a portal and several portal pages. The following graphic illustrates the required portal
pages and the typical navigation between them:
Add the following portal pages to the portal:
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 545
Chapter 7: Customizing the user experience
Page Object Page Type Description Authentication
Required
Main None Generic Links to the Login No
and Self-Registration
pages
Self-Registration Visitor Object Create Allows a new visitor No
to enter some
personal info,
including login name
and password
Login Page Visitor Login Form Allows a registered No
visitor to log in to the
portal
Visitor View Visitor Object View Displays personal Yes
information and a list
of comments created
by the current visitor
Edit Visitor Visitor Object Edit Allows an existing Yes
visitor to change
some personal
information including
the login name and
password
Create Comment Comment Object Create Allows the creation Yes
of a new Comment
record. The current
visitor is
automatically related
to the new Comment
record (and vice
versa).
This portal has the following requirements for permissions:
• Portal users can create, view and edit their own personal visitor information (their own record).
• Portal users cannot access personal records of other visitors.
• Portal users can create and view (and optionally edit and delete) their own comments.
• Portal users cannot access comments created by other visitors.
To satisfy these requirements, you would set the following permissions on the Visitor and Comment objects:
Object Role Access Granted
Visitor Portal User Create
Visitor Record Creator View, Edit
546 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Hosted files
Object Role Access Granted
Comment Portal User Create
Comment Record Creator View
In this design, any portal user can create a new Visitor record - this represents self-registration. But the View
privilege is granted only to the Record Creator. This means that an authenticated visitor can only view their
own personal record. If a visitor tries to access data of another visitor, they'll be denied access.
You can assign permissions to the Record Creator role from the Permissions section of an object definition's
details page.
You can assign permissions through the relationship between the current user and records the same way as
you can between a regular user and records (see Role-based access control on page 648).
Hosted files
As with most websites, in portals you often need to make use of and reference files such as images, Flash
movies, JavaScript, CSS, etc. These files are typically referenced in web pages through <IMG>, <SCRIPT>
and other HTML tags. Rollbase provides a convenient way to host and reference arbitrary files through a
mechanism called Hosted Files.
For example, using this feature, you can upload and use third party and custom JavaScript and CSS libraries
in your portals to create a unique user experience and look and feel. JavaScript hosted files can be very useful
in development of both client-side and server-side scripts. You can preview these files while working in the
formula editor using the drop-down list View JS Hosted Files.
Hosted files can be included as part of published applications just like other application components (e.g.
portals, objects, etc.)
Hosted files are most often used in portal pages, but they can also be used in Rollbase object pages.
You can prepare a CSS Stylesheet with all tags used by the Rollbase UI (see Rollbase CSS Styles for the
Classic UI on page 1293) and upload this CSS as hosted file. In this case, you could use hosted CSS to customize
the appearance of all pages in your tenant. For information on hosting CSS, see Advanced setup and
administration on page 713.
You can reference hosted files using merge fields in various scenarios such as in template and formula fields,
HTML and script components in pages, as well as within email and document templates. Using hosted file
tokens in email templates provides a convenient way to add email attachments. See Hosted file tokens on
page 548 and Using hosted file tokens on page 549for more information.
Managing hosted files
Hosted files can be associated with one or more applications. You can modify text-based hosted files, such as
JavaScript, HTML, or XML, by simply modifying the text within Rollbase without uploading a new file.
To upload and manage hosted files from setup:
1. Navigate to the Setup home page:
• From an application page, do one of the following:
• Select Setup Home from the Rollbase menu.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 547
Chapter 7: Customizing the user experience
• Select Setup Home from the application switcher
• From a setup page, select Setup Home from the application switcher
2. In the Applications Setup section, click Hosted Files.
3. To create a new hosted file, click New Hosted File and:
• Enter a display name.
• Browse to upload the file (the size of a single uploaded file cannot exceed maximum allowed for Rollbase
installation (5MB by default)).
• Optionally enter a description.
• Select the applications to which this file should be attached.
Hosted file tokens
The following table summarizes the usage of merge field tokens corresponding to different types of hosted
files:
Token name Where used Replaced with
Filename Anywhere, for example: URL to the file hosted by Rollbase.
{!#HOSTED_FILE.7034090} When used in an email template,
the hosted file is added to the email
as an attachment instead of as a
URL in the email body.
Filename [image] Any template field or page-level HTML <img> tag with URL to an
HTML or Script component, for image file. This works similarly to
example: <img shared Image fields.
src='{!#HOSTED_FILE.7034090}'
border='0'
align='absmiddle'/>
Filename [text] Any template field or page-level Entire text of the hosted file. This
HTML or Script component, for approach has many possible
example: usages, such as using custom
{!#HOSTED_FILE.13687907#text} JavaScript libraries in server-side
formulas.
548 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Hosted files
Using hosted file tokens
When editing any of these components in the Template Helper, select the Hosted Files group, select the
merge field token corresponding to the desired hosted file, and paste it into your template:
Example using tokens in formulas
The following example illustrates the usage of hosted JavaScript files in server-side formulas (using the
filename[text] format described above). Assume you have created and uploaded a JavaScript file that contains:
function my_func(x, y) {
return x+y;
}
You can create a server-side formula which uses this file by using the hosted file's filename[text] merge token
and invoking the function, as follows:
{!#HOSTED_FILE.499203#text}
my_func({!num1}, {!num2});
If you use the formula debugger to debug this formula, it will be parsed in the following form:
function my_func(x, y) {
return x+y;
}
my_func(100, 200);
Note: When using JavaScript functions in server-side formulas, do not use a standalone return statement;
doing so will cause an error. The result of the very last JavaScript statement (typically a function call) will be
used as the formula result.
For information about server-side APIs, see Server-side API on page 949.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 549
Chapter 7: Customizing the user experience
550 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
8
Supporting mobile users
When deciding how to expose Rollbase application data to users on tablets and smartphones, it is important
to weigh the necessary functionality against the resources and skills available within your organization.
Requirements for mobile support vary widely. Rollbase Web applications provide responsive design, making
it possible to simply allow mobile users to access the application from a browser. Rollbase also supports
adaptive features; you can detect the type of device and customize the experience accordingly. On the other
hand, to use native OS features that are not available to browser-based applications or to distribute an application
from Apple, Android, or Windows app stores, you can take advantage of the Rollbase integration with the
Telerik platform to build a hybrid mobile app. In this case, it is important to consider time constraints and the
skill set required because designing and developing a mobile app with a good user experience can be complex,
especially for smartphones.
In summary, the options available to support mobile users include:
• Rollbase responsive and adaptive user interface — Rollbase's user interface provides an out-of-the-box
Web UI that works well across various device sizes and platforms. See Responsive user interface on page
431 for more information. You can create one design that runs well on a variety of platforms with minimal
effort. You can tailor the workflow and user experience based on whether users access the app from a
desktop, tablet, or mobile phone. See Adaptive user interface on page 408 for more information about
customization.
• Building a hybrid mobile app with Telerik Platform — The Telerik Platform makes it easy to create apps
™
that use native OS features and/or can be distributed in app stores. The Telerik Platform provides an
integration with Rollbase that allows you to access Rollbase data from a native or hybrid mobile app. Rollbase
generates metadata catalogs that provide the schema necessary for a mobile (or any external) app to create,
update, and delete records and a Progress Data Service that handles the requests. Use of the Progress
Data Service and data catalogs provide an alternative to calling Rollbase APIs directly.
See the following for related information:
• Watch a video that demonstrates how to access Rollbase data from a hybrid mobile app.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 551
Chapter 8: Supporting mobile users
• To use Progress Data Catalogs with the Telerik Platform, see Using the Telerik Platform to create a
mobile app on page 552
• For general information on the CDO standard (maintained by Progress Software) see
http://clouddataobject.github.io/
Note: Rollbase Mobile-Web enabled application — For customers using the Rollbase Classic UI, this legacy
option supports non-customizable, Rollbase-generated mobile apps that you can enable per Rollbase Web
App. This functionality was formerly known as Mobile Edition and offers none of the responsive or modern
design options of those available in the new Rollbase UI. You choose the application objects and the associated
views exposed to users through the mobile app, but you cannot change the look and feel of the mobile app
itself. Users logging in to their usual application URL with a mobile device will be redirected to the mobile-web
application. See Mobile-Web enabled applications on page 579 for details.
For details, see the following topics:
• Using the Telerik Platform to create a mobile app
• Mobile-Web enabled applications
Using the Telerik Platform to create a mobile app
The Telerik Platform, similar to Rollbase, is a cloud-based environment. Telerik Platform supports development
of modern mobile apps using Kendo UI widgets, HTML5, JavaScript, jQuery, and Cordova plug-ins and offers
back-end services such as push notifications.
Use of the Telerik Platform requires a Telerik account. The Telerik Platform supports two approaches for building
a mobile app, starting with the views (UI) or starting with the code. These were formerly in separate development
environments known as ScreenBuilder and AppBuilder, respectively. Starting in December of 2015, when
working on an app, you can access ScreenBuilder functionality by selecting Views from the menu and access
AppBuilder functionality by selecting Code.
A sample Progress Data Service project is available for the code first approach. It demonstrates basic
functionality, but you cannot add views to it from the Views service. Progress recommends using the sample
to exercise the connection with Rollbase. When developing a new mobile app, it is better to start with the views
first approach.
The high level steps for creating a mobile app to access Rollbase data include the following:
• In your Rollbase account:
1. Decide which objects the mobile app will access and create a Progress Data Catalog that includes those
objects.
Rollbase provides an All Objects data catalog, which contains all the objects in your tenant. You can
create additional catalogs with subsets of objects. For example, for simplicity and security a catalog
should only include the objects that the mobile app needs to access. Related objects must explicitly be
included in the catalog. You can view and manage catalogs from Setup Home or from individual
application setup pages. To include a catalog file when generating application XML to distribute the app,
you need to create or attach it from the application setup page.
See Creating Progress Data Catalogs for use in the Telerik Platform on page 553 for more information
about creating a data catalog.
2. Identify the following values:
552 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Using the Telerik Platform to create a mobile app
• Progress Data Service URL: The server location of Progress Data Services. Navigate to Setup
Home > Applications Setup > API to find this URL.
• The location of the catalog:
• If you download the catalog locally, you can browse and upload it in Telerik Platform.
• To use the catalog stored by Rollbase, find the URL on the Progress Data Catalog view page.
Navigate to Setup Home > Applications Setup > Progress Data Catalogs to find this URL.
3. Identify the integration name of the object and the fields that you want to display. You can find these
names by viewing the object definition:
• Locate the Integration Name in the Object Properties section.
• Locate the Fields section and the Integration Name column.
• In your Telerik Account, create a mobile app using one of the following approaches:
• Build the screens first as described in Using the Views first approach on page 554.
• Use the sample Progress Data Service project as described in Creating a mobile app using Code and
the Progress Data Service template on page 575.
Watch a video that demonstrates how to access Rollbase data from a hybrid mobile app.
To use Kendo UI controls in your app, you write code to bind the widgets to objects corresponding with those
in the Progress Data Catalog that you create in Rollbase. Examples illustrating use of PDOs and JSDOs are
available from the gitub site, http://clouddataobject.github.io/. The Progress Data Objects Guide and Reference
contains the latest documentation describing how to access JSDOs from Kendo controls.
For more information on the Telerik Platform, see the following documentation:
• Telerik Platform: http://docs.telerik.com/platform/help/getting-started/introduction
• Kendo UI: http://docs.telerik.com/kendo-ui/introduction
Creating Progress Data Catalogs for use in the Telerik Platform
Rollbase updates data catalogs with any changes made to the application object model. In the Telerik Platform,
you can use a URL that points to a catalog or you can download the catalog from Rollbase and upload it to
Telerik Platform. If you download and upload the catalog, you are responsible for updating it when necessary.
For example, if you make any changes to the objects in Rollbase, such as adding or removing a field, you will
need to download the updated catalog from Rollbase and upload it to the Telerik Platform again.
To create a new data catalog, follow these steps:
1. Create the catalog from Setup Home or from the application setup page:
• Navigate to Setup Home. From the Applications Setup section, select Progress Data Catalogs. Or,
• Navigate to the application setup page Catalogs section.
2. Click New Progress Data Catalog.
The Progress Data Catalog screen opens.
3. Specify the following:
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 553
Chapter 8: Supporting mobile users
• Catalog Name: A unique name for the catalog.
• Integration Name: A unique integration name that Rollbase uses to identify this catalog in the customer
tenant.
Rollbase automatically assigns an Integration Name derived from the Catalog Name, but you are free
to change it.
• Description: Optional description of the catalog.
• Objects: In the Select Objects section, select and move the required objects from Available to Selected.
4. Click Save to save the catalog definition.
Rollbase creates the new catalog and displays it in the list of catalogs.
Using the Views first approach
Follow these general steps to create a mobile app using the Views service that accesses Rollbase data:
1. Create an app in the Telerik Platform, as described in Create the app on page 554.
2. Add a Progress Data Service provider that allows the app to access Rollbase data, as described in Add a
Progress Data Service provider on page 556.
3. Create and test the initial views (screens), as described in Create or configure an Authentication view on
page 560 and Create a Master Detail view on page 566.
4. Configure navigation and customize code to complete development of the app, as described in Configure
navigation and extend the app with Code on page 571.
For information about creating a mobile apps using Code (formerly the AppBuilder), see Creating a mobile app
using Code and the Progress Data Service template on page 575.
Create the app
Follow these steps to create a mobile app using the Telerik Platform in the Views first approach:
1. Log into the Telerik Platform.
2. Click + Create app.
The Create App screen displays:
554 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Using the Telerik Platform to create a mobile app
3. Enter an App name and an optional Description.
4. Click Create App.
The new project opens with the Views screen in focus:
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 555
Chapter 8: Supporting mobile users
This project window contains the following panes:
• The menu bar down the left side provides global features for building the app, such as Views and Code.
• The menu bar displayed for the Views selection provides access to a menu of functions for building the
app using Views.
• The left pane beside the Views menu displays options associated with the current menu choice, such
as a function for adding views with Manage Views selected and a list of views that are currently created
for the app. Initially, this pane shows a starting view (Home View) for you to use to create your first view
(not used in this example).
• A center pane (if displayed) shows properties associated with an app element selected in the left pane,
such as, initially, creation of the starting view.
• A right pane (if displayed) that provides a simulated display of the currently selected view using one of
the available device simulators.
Add a Progress Data Service provider
To allow the mobile app to access Rollbase data, you must configure a Progress Data Service provider to
access the Rollbase data as a service. Follow these steps to configure the provider:
1. With the app open in the Views window, click Data Providers:
556 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Using the Telerik Platform to create a mobile app
2. Click Add Provider and select Progress Data Service from the drop-down menu.
The Connect to a Progress Data Source dialog opens:
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 557
Chapter 8: Supporting mobile users
3. Enter the following values:
• Provider Name — The name to be used when referencing the provider in app code. The name can only
contain letters and numbers with no spaces. Defaults to progressDataProvider.
• Provider Title — The name Telerik Platform will display for this provider. Defaults to Progress Data
Service.
• Service URI — The server location of Progress Data Services. See how to locate this URI.
• Catalog URI — The location of the catalog. See how to locate this URI.
• Catalog File — Allows you to upload the catalog file to your Views project either from the location
specified by a URI (typically, Catalog URI) or from a physical file location that you browse to. This allows
you to select objects and fields wherever you need to enter them as values for view properties, but if
anything changes in the Rollbase application, you will have to re-upload the catalog. If you access the
catalog from its URI without uploading it, you must enter the names of these resources manually, but
Rollbase automatically updates the catalog whenever there are changes to the application.
• Authentication model — Select Form from the drop-down list.
The following screen shows the dialog with values:
558 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Using the Telerik Platform to create a mobile app
Note: The Catalog URI in this example is set to
https://web-pac-int.rlb-test.progress.com/rest/jsdo/catalog/Lending_Library.json.
4. Optionally, you can select Add an "Authentication" view to my app, which creates a login screen for you.
See Create or configure an Authentication view on page 560 for details.
5. Click Add.
Either the new provider information displays in the center pane, or if you selected Add an "Authentication"
view to my app, the new view appears in the left pane and the new Authentication View properties display
in the center pane, with the General option selected to show the General Settings.
Next, create or configure the Authentication view.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 559
Chapter 8: Supporting mobile users
Create or configure an Authentication view
To access Rollbase data from a mobile app, users must log in to Rollbase using their Progress ID and password.
The Authentication view provides this functionality.
If you already created a Progress Data Service provider and selected Add an "Authentication" view to my
app, select the view and start with Step 3 on page 561. Otherwise, to create an Authentication view for a
Progress Data Service provider, start with Step 1 on page 560:
1. With the app open in the Views window, select the Manage Views tab and click Add View:
2. From the palette of view types, select Authentication:
The new Authentication View properties display in the center pane, with the General option selected to
show the General Settings:
560 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Using the Telerik Platform to create a mobile app
3. Review and change the following General Settings:
a) Optionally, change the name of the view by editing the Name field. The app code will refer to this name.
Note: You can only modify this field before clicking Apply.
b) Optionally, change the value in the Title field, for example to Log In, which changes the label for the
view in the left pane and specifies the heading that displays in the app screen for this view.
c) Expand the Navigation node and select Include this view in the app navigation. By default, an icon
is selected to represent this view in app navigation. Optionally, you can change this icon by opening and
selecting a different icon, as shown below:
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 561
Chapter 8: Supporting mobile users
d) Expand Data Binding and verify that a Progress Data Service provider is selected, or create one if
you have not already done so. See Add a Progress Data Service provider on page 556 for details.
4. Under Authentication View, click the Sign In option to scroll to the Sign In Screen properties, then expand
and change the settings as follows:
a) Expand Email. In the Textbox label field, optionally change the label you want to appear for the field
representing the user name. For example, you might enter Progress ID for connecting to a Progress
Data Service for Rollbase. Optionally, enter text in the Help text field. This text will appear in the field
in the app.
When editing a view, you can click Apply at any time and test it in the device simulator. For example, if
you click Apply now, the screen below shows the Authentication view after typing Progress ID (along
with the previously suggested settings):
562 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Using the Telerik Platform to create a mobile app
Note: The Authentication View properties scroll back to the General Settings after you click Apply.
Note also that the Register button, if it appears as displayed in the simulation, is not needed for this
example app.
b) To remove the Register button, expand Configuration / Options and deselect Enable "Register"
screen. This disables the Register button from the view—click the Sign In option, again, to continue.
c) Expand Password. In the Textbox label field, optionally change the label you want to appear for the
field representing the password. Optionally, enter text in the Help text field. This text will appear in the
field in the app.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 563
Chapter 8: Supporting mobile users
d) Expand Confirm button. Optionally, change the label you want to appear on the confirm button, for
example, to Log In.
e) Expand Redirect and select the view to display after a successful log in, if you have created one. (We
return to this step, later, after creating a Master Detail view.)
5. Click Apply.
The device simulator displays your changes similar to the following screen, which shows the completed
Authentication view in the device simulator with the device iPhone 6 selected:
564 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Using the Telerik Platform to create a mobile app
To test the view, enter a valid Progress ID and password in the device simulator.
Next, create a Master Detail view.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 565
Chapter 8: Supporting mobile users
Create a Master Detail view
A Master Detail view displays a list of values. When connecting to Rollbase data, this is typically a list of values
from a single field for a group of records. Optionally, you can also display a form with multiple field values from
the single record associated with a value selected in the list.
To create a Master Detail view from the Views window, follow these steps:
1. Select the Manage Views tab and click Add View.
2. From the palette of view types, select Master Detail.
This creates a new Master Detail view labeled Master Detail. The new Editable List View properties
display in the center pane, with the General option selected to show the General Settings.
3. Review and change the following General Settings:
a) Optionally, change the name of the view by editing the Name field. The app code will refer to this name.
Note: You can only modify this field before clicking Apply.
b) Optionally, change the value in the Title field, for example to Library Titles, which changes the
label for the view in the left pane and specifies the heading that displays in the app screen for this view.
c) Expand the Navigation node and select Include this view in the app navigation. By default, an icon
is selected to represent this view in app navigation. Optionally, you can change this icon by opening and
selecting a different icon.
d) Expand the Data Binding node. And do the following:
• Verify that the Progress Data Service provider you want to use for this app is selected in the Provider
field. You can also create a Progress Data Service provider at this point if you have not already done
so, then return to finish creating this view. See Add a Progress Data Service provider on page 556 for
details.
• In the Content type field: If you are accessing the Progress Data Catalog directly from its URI, enter
the integration name of the Rollbase object type for which you want the view to display records, for
example, Title. See how to locate the integration name. If you uploaded the Progress Data Catalog,
select the object integration name from the selector list.
4. Under Editable List View, click the List option to scroll to the List Screen properties, then change the
settings as follows:
a) In the Heading text field: If you are accessing the Progress Data Catalog directly from its URI,enter the
integration name of the Rollbase field whose value you want to display in the list for each record of the
Rollbase object, for example, name. If you uploaded the Progress Data Catalog, select the field integration
name from the selector list.
b) Leave the Configuration settings unchanged.
c) Expand Item Action, and ensure that Open item details is selected.
d) Click Apply to update the app with these changes to your Master Detail view.
Telerik Platform saves your changes and the device simulator displays the resulting view. The device
simulator cannot display Rollbase data until you log in, so ignore the loading icon. Also, before seeing the
data, you need to set your Authentication (now Log In) view to navigate to this Master Detail (now Library
Titles) view after a successful log in.
5. Select the Log In view in the views pane, and follow these steps to set navigation for a successful log in:
566 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Using the Telerik Platform to create a mobile app
a) Under Authentication View, click the Sign In option to scroll to the Sign In Screen properties.
b) Expand Redirect and select Library Titles, as follows:
c) Click Apply to update your Log In view with this change.
6. In the Log In view simulation, enter your Progress ID and Password credentials, then click the Log In
button.
The Library Titles screen displays in the device simulator showing the list of titles from your Progress
Data Service, similar to the following:
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 567
Chapter 8: Supporting mobile users
Note that if you select any of the items in the list, the simulator displays an empty Detail screen. You need
to add fields whose values you want to display for any item that you select.
7. In the views pane, select the Library Titles view to open its properties.
8. Under Editable List View, click the Detail option to scroll to the Detail Screen properties, then change the
settings as follows:
568 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Using the Telerik Platform to create a mobile app
a) Under the Heading text property, select Static to use the default, or enter your own literal value, for
example, Title Information, which displays as the heading for the detail screen.
b) For each field that you want to display in the detail screen, click + Add Field and select a text and visual
element, such as Short text, to use for the field.
A group of field properties appears below + Add Field for each field you create, in the order you created
it, identified by the type of field element (such as Short text) that you chose to represent its value. All
element types contain a Name, Data Binding or Text, and optional Format setting. For the Short text
fields used in this example, there is also a Label setting to identify the field.
c) For each field element, enter a unique value for the Name property. The app code will refer to this name.
Note: You can only modify this field before clicking Apply.
d) For each Short text element, enter a value to display as a label for the field, such as Title:,
Author(s):, or Publisher:, as you will see in the example screen.
e) For each field element: If you are accessing the Progress Data Catalog directly from its URI, enter the
integration name of the Rollbase field whose value you want to display for the record associated with
the item that is selected in the list, for example, name, Author_s_, or Publisher, whose values you
will see in the example screen. If you uploaded the Progress Data Catalog, select the field integration
name from the selector list.
9. Once you have finished the settings for your Detail Screen properties, click Apply to save them.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 569
Chapter 8: Supporting mobile users
10. Select the Log In view in the views pane and, again, enter your credentials (if they are not already entered)
in the device simulator, then click the Log In button.
The Library Titles screen, again, displays in the device simulator showing the list of titles, as shown in Step
6 on page 567.
11. If you select the second item, Through the Glass Looking, the new Title Information screen displays in
the device simulator, similar to the following:
Next, configure navigation for app start up and customize your app with code.
570 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Using the Telerik Platform to create a mobile app
Configure navigation and extend the app with Code
Accessing data from a Progress Data Catalog requires authentication from Rollbase, so users must log in to
view data. Navigation options allow you to specify the initial view of an app and which view to open upon a
successful log in. In order to test your Master Detail view, you have already set the view to open for a successful
login as described in Create a Master Detail view on page 566. The steps below use the example built in the
previous topics.
Follow these steps to display the Authentication view first after initial app start up:
1. With the app open in the Views window, select Navigation Layout.
Navigation options display in the center pane:
2. Expand the Application start up node.
This initially shows the default view (Home View) selected as the Initial view setting.
3. From the Initial view drop-down list, select the Authentication view you created previously (Log In).
4. Click Apply to save your change.
Next time you open this app in the Telerik Platform, it opens to the selected view, much like the app opening
on a device.
5. If you want, you can now remove the unused Home View from your app by:
a) Selecting Managed Views from the Views menu.
b) Clicking the tool icon next to view to display its drop-down menu:
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 571
Chapter 8: Supporting mobile users
c) Selecting Delete in the drop-down menu:
The Telerik Platform deletes the view from the list after you confirm that you want to do this.
Note: This Delete option is disabled if the view is part of app navigation or referenced in other views of
the app.
The device simulator also now displays your app without the Home View in its navigation panel:
572 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Using the Telerik Platform to create a mobile app
6. When you are satisfied with the app, click Commit changes in the menu bar. This commits all of your
changes to source control.
To add custom code to the app, select Code from the menu. The project opens in the Code window, formerly
known as AppBuilder. The Project Navigator pane displays the source code for the views and data provider
you created. You can add custom code, build the app, and run the app in the device simulator as you make
changes:
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 573
Chapter 8: Supporting mobile users
Note: If you add custom code to the app, you must add it between the comments starting with
START_CUSTOM_CODE and ending with END_CUSTOM_CODE (the rest of the comment is based on the name
of the component).
For example, in JavaScript files:
// START_CUSTOM_CODE_dataListView
// END_CUSTOM_CODE_dataListView
For example, in HTML files:
<!-- START_CUSTOM_CODE_dataListViewModel -->
<!-- END_CUSTOM_CODE_dataListViewModel -->
If you reopen the app, custom code added elsewhere in the source files is likely to be lost.
574 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Using the Telerik Platform to create a mobile app
Creating a mobile app using Code and the Progress Data Service
template
Follow these steps to try a sample mobile app that accesses Rollbase data and is built using the Code service:
1. Create an app using the Progress Data Service template, as described in Create the app on page 575.
2. Specify the settings, as described in Configure JSDO settings on page 577.
3. Test your app and see the starter implementation, as described in Test the app on page 579.
4. Bind Kendo UI widgets to the Rollbase data service and access Rollbase data using the JSDO dialect of
the Kendo UI DataSource, as described in the Progress Data Objects Guide and Reference.
For information about creating a mobile app using Views (formerly the Screen Builder), see Using the Views
first approach on page 554.
Create the app
To use the Progress Data Service template, create an app as follows:
1. Log into the Telerik Platform.
2. Click + Create app.
The Create App screen displays.
3. Select the Advanced card.
A list of samples and templates displays.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 575
Chapter 8: Supporting mobile users
4. Select the Progress Data Service template.
5. Enter an App name and an optional Description.
6. Click Create App.
The new project opens. Your screen should look similar to the following:
576 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Using the Telerik Platform to create a mobile app
Next, configure JSDO settings so the app can connect to Rollbase.
Configure JSDO settings
The Progress Data Service template contains a home page and two app pages:
• A login page that allows you to use your credentials to log into your Rollbase tenant
• A list page that displays a list of values from one or more fields in Rollbase records
Note: A project created with the template includes a README.txt file that describes how to use the template
and how to configure settings. This file will be updated periodically, you can check it for the latest information.
After creating the app with the Progress Data Service template, follow these steps in the Code window to
provide the necessary settings:
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 577
Chapter 8: Supporting mobile users
1. In the Solution pane, navigate to the the scripts folder and expand it.
2. Double-click to open the jsdoSettings.js file.
3. Change the placeholder values for the following settings:
a) serviceURI: The Progress Data Service URL. Typically,
http://<server_location>/rest/jsdo/. In Rollbase, navigate to Setup > Applications Setup
> API to find this value.
b) catalogURIs: The Progress Data Catalog URL. Typically,
http://<server_location>/rest/jsdo/catalog/<Catalog_Integration_Name>.json.
In Rollbase, click the catalog name to view the catalog and find the URL value:
Alternately, if you downloaded the catalog locally, you can include it in your Telerik Platform project and
provide the relative path to the project directory location as the catalogURIs value. For example, in
your Telerik Platform project directory, you can create a new folder, catalogs, upload the file to your
project in that location, and then use catalogs/<Catalog_Integration_Name>.json as a value
for the catalogURIs setting.
c) For authenticationModel, use one of the following:
• form: session-based authentication that accepts the credentials that you use when you log into
Rollbase.
• basic: basic authentication that is similar to form, but requires an additional Customer ID, which
must be appended in the format loginName@custId. To find your Customer ID, open the Rollbase
menu and select Subscription Details. The About Your Account page opens. Customer ID is
listed on the page. See The Rollbase Menu and Help on page 30 for more information.
4. For displayFields, use the field integration names for the values you want to display in a
comma-separated list with or without spaces.
5. For resourceName, use the object integration name.
6. Save the file.
The following is an example of the file with the required values set, including three fields:
578 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Mobile-Web enabled applications
Next, Test the app on page 579.
Test the app
To test your mobile app, follow these steps:
1. From the menu bar, select Run and the simulator for the selected device.
The simulator opens.
2. Select the Login page.
3. Enter credentials for your Rollbase account and log in.
Note: If you used basic authentication in the JSDO settings, the user name has to be in the format
loginName@custId and the password for your account. To find your Customer ID, open the Rollbase
menu and select Subscription Details. The About Your Account page opens. The Customer ID is listed
on the page. See The Rollbase Menu and Help on page 30 for more information.
4. Select the List page.
The values for field display.
Congratulations, you successfully tested a mobile app that accesses Rollbase data! What's next? See
http://docs.telerik.com/kendo-ui/introduction to learn more about Kendo UI controls and see the Progress Data
Objects Guide and Reference for information about accessing Rollbase data using JSDOs and Kendo controls.
Mobile-Web enabled applications
Rollbase applications can be easily accessed on iPhone and Android devices using an interface generated by
Rollbase designed for smart phone browsers. The screenshots below illustrate the core capabilities of the
Rollbase Mobile-Web user interface. Existing Rollbase applications can be mobile-enabled in just a few clicks,
as described in Enabling Mobile-Web.
Secure Log In
Users log in to a hosted or Private Cloud Mobile Web-enabled application from a dedicated mobile login page.
The standard Rollbase login page automatically redirects smart phone browsers to this mobile-friendly page.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 579
Chapter 8: Supporting mobile users
Browse Applications
Users who have permissions to access a Mobile-Web enabled app will see it in the list of available applications
when they log in.
Browse Records
Users can select views they have access to and navigate the records in those views. Flagged records will be
shown with the standard flag icon and unviewed records will be shown in bold blue text.
580 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Mobile-Web enabled applications
View Records
Selecting a record displays a detail view showing each of the record's values organized into sections defined
by the object's default view page layout. Administrators can customize how this page is organized. Users can
select Email addresses to send emails and phone numbers to make a call directly from their phone.
Switch to Browser Version
Users can switch to the standard Rollbase browser interface to access all of the features not available in the
Mobile UI by clicking Switch to Browser Version at the bottom of any page.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 581
Chapter 8: Supporting mobile users
Enabling Mobile-Web
Navigate to the application definition and from the More Actions drop-down menu, select Set Mobile-Web
Options. Select the check box to enable Mobile-Web and move the menus, or tabs, that contain the views to
expose to mobile users to the Selected Menus list.
582 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
9
Integrating with outside sources
Rollbase offers a variety of mechanisms for integration. You can bring external data and external structures
into Rollbase applications and you can make Rollbase metadata and data available to external applications.
Rollbase objects that access data from external data services are called Rollbase external objects.
For details, see the following topics:
• Creating Rollbase objects from OpenEdge Object Services
• Using DataDirect Cloud to access external data
• Calling Progress Corticon decision services from Rollbase
• Creating a Rollbase application from Microsoft Access
• Creating a Rollbase application from a Salesforce application
• Using external tables as Rollbase objects
• Importing data
• Deleting multiple records by importing a spreadsheet
• Exporting from views and reports
• Integrating with Google applications
• Using SOAP or REST to integrate with Rollbase
• Integrating apps using Cloud Data Objects
• Integrating with Microsoft Exchange Server
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 583
Chapter 9: Integrating with outside sources
Creating Rollbase objects from OpenEdge Object
Services
Rollbase external objects can be associated with OpenEdge Data Objects hosted on an OpenEdge application
server. An OpenEdge Data Object is a resource that provides well-defined client access to OpenEdge data
and business logic on an OpenEdge application server. When you associate Rollbase external objects with
OpenEdge Data Objects, the data persistence for these objects is handled by the OpenEdge application server.
To provide integration with Rollbase, OpenEdge developers create at least one Data Object Service and its
Data Service Catalog, which defines the OpenEdge Data Objects they want the service to expose to clients
(in this case, Rollbase external objects). This process is described in the OpenEdge documentation, specifically
in the Data Object overview chapter of Progress Developer Studio for OpenEdge Online Help.
OpenEdge developers deploy a Data Object Service that they create with one or more OpenEdge Data Objects
either to a Progress Application Server for OpenEdge (PAS for OpenEdge) or to a generic Tomcat web server
running OpenEdge REST with access to the OpenEdge AppServer. The endpoints will need to be accessible
over HTTP(S) to the Internet for Hosted Rollbase users or to the Rollbase instance for Private Cloud users.
The appropriate security settings are necessary to protect these endpoints. Using Basic Authentication over
HTTPS is a recommended deployment option. Different security models can be used during development and
deployment. For example, you could develop with anonymous access over HTTP and change the Service URI
to HTTPS and add Basic Authentication at a later date without reimporting the Data Service Catalog.
Once the OpenEdge side is set up, you can import an OpenEdge Data Service Catalog (called a JSDO Catalog
in the Rollbase user interface) to create Rollbase external objects or to create a new Rollbase application.
Either way, you need the following information before starting the integration:
• The file location of the Data Service Catalog
• The URI for the Web application where the OpenEdge Data Object Service is deployed
• If using Basic Authentication, the username and password required to access the Web application where
the Data Object Service is deployed
Note: When using REST or SOAP APIs to create, update, or delete external objects linked to OpenEdge Data
Object Services, you need to supply both the object integration name as a string and an object ID. See the
SOAP and REST APIs described in Metadata API and XML Reference on page 1158, Rollbase REST Methods
on page 1201, and Rollbase SOAP Methods on page 1322.
Limitations
The following limitations apply when creating Rollbase external objects associated with OpenEdge Data Objects:
• OpenEdge Data Objects are only certified with Progress OpenEdge 11.3.2, 11.3.3, 11.5, 11.5.1, and 11.6.
• Only single-table data sets can map to a Rollbase external object.
• Rollbase creates objects with fields that match OpenEdge resource columns. If a field has a name that
cannot be used in Rollbase, such as a field that contains hyphens, it will be skipped.
• Arrays in OpenEdge are not imported.
• OpenEdge Data Objects do not support the following object attributes available in Rollbase:
• Organization
584 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Creating Rollbase objects from OpenEdge Object Services
• Portal User
• Approval
• Survey
• Survey Taker
• Queue
For information about the object attributes that an OpenEdge Data Object supports, see Enabling object
attributes for an OpenEdge Data Object on page 599.
• Relationships involving OpenEdge Data Objects support only the following scenarios:
• 1-1 or 1-N cardinality when establishing a relationship between an OpenEdge Data Object and another
OpenEdge Data Object or a Rollbase native object
• 1-1 or N-1 cardinality when establishing a relationship between a Rollbase native object and an OpenEdge
Data Object.
• JSDO supports an Invoke method apart from CRUD operations. Accessing this Invoke method from Rollbase
Object script requires a Client Principal token. This token is “{!#CP_TOKEN}”, and can be used in an HTTP
header under the header name ‘X-OE-CLIENT-CONTEXT-ID’. Example:
var headers = {
'X-OE-CLIENT-CONTEXT-ID' : '{!#CP_TOKEN}'
};
rbv_api.sendJSONRequest('{!ttBPMDomain1151.resourceURI#jsdo}', '', 'GET',
'application/json', '', '', headers);
Supported data types
The following OpenEdge data types will be converted to Rollbase fields. You can change the field type in
Rollbase when you import from the OpenEdge Data Service Catalog or at a later time using the Rollbase field
Convert action.
OpenEdge data type Rollbase data type Notes
CHARACTER Text Can be converted to many more
specific Rollbase types, including
the Document Template type
DATE Date string (ISO 8601 formatted string of
the form "yyyy-mm-dd")
DATETIME DateTime string (ISO 8601 formatted string of
the form
"yyyy-mm-ddThh:mm:ss.sss")
DATETIME-TZ DateTime string (ISO 8601 formatted string of
the form
"yyyy-mm-ddThh:mm:ss.sss+hh:mm")
DECIMAL Decimal Can be converted to Currency or
Percent
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 585
Chapter 9: Integrating with outside sources
OpenEdge data type Rollbase data type Notes
INT64 Integer Integer
INTEGER Integer
LOGICAL Checkbox
LONGCHAR Text Area Can be converted to other text types
and to the Document Template type
ROWID Text OpenEdge special type - typically
read only - string (Base 64 encoded)
Linking Rollbase external objects to OpenEdge data
You can create Rollbase external objects with data exposed by OpenEdge Object Services. You do this by
specifying an OpenEdge Data Service Catalog file and an OpenEdge URI as described in Creating Rollbase
objects from OpenEdge Object Services on page 584.
After you create a Rollbase external object, the data is linked. When the Rollbase application creates or modifies
an object record, the data is also added to or modified in the OpenEdge database. If the data is modified in
OpenEdge, the Rollbase record is updated when the page is refreshed.
To create Rollbase external objects from an OpenEdge Object Service:
1. Navigate to the target application.
2. Click + on the application menu bar.
586 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Creating Rollbase objects from OpenEdge Object Services
3. Select A new Object (with Tab) from an External Metadata and click Create.
The Import Object Metadata page opens:
4. Select OpenEdge Service and click Next.
The Import Objects from OpenEdge Services page opens.
5. Specify the following:
If you are using Hosted Rollbase:
• OpenEdge JSDO Catalog — The OpenEdge Data Service Catalog file that defines the object. Progress
recommends that you refer to the Enabling support for filtering options and sorting on page 590 to learn
what a Data Service Catalog must include to fully use Rollbase functionality.
• Service URI — The URI for the Web application where the OpenEdge Data Object Service is deployed
• No Authentication — Specifies that no login credentials are required to access the service URI
• Basic Authentication — Specifies that the login credentials you create be used to access the service
URI. If you select this option, you must specify the Login Name and Password you want to use to
access Rollbase.
If you are using Rollbase Private Cloud:
• OpenEdge JSDO Catalog— The OpenEdge Data Service Catalog file that defines the object. Progress
recommends that you refer to the Enabling support for filtering options and sorting on page 590 to learn
what a Data Service Catalog must include to fully use Rollbase functionality.
• Service URI — The URI for the Web application where the OpenEdge Data Object Service is deployed
• No Authentication — Specifies that no login credentials are required to access the service URI
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 587
Chapter 9: Integrating with outside sources
• Use Current User (if OpenEdge authentication is enabled) — Specifies that OpenEdge credentials
are required to access the service URI. This is the default option for users accessing Rollbase using
OpenEdge credentials and this option is not available for non-OpenEdge users.
Note: If the OpenEdge Object Service is configured with Single Point Authentication, Rollbase must
also have OpenEdge authentication configured for it, and as a prerequisite, you (a Private Cloud user)
must copy a set of JAR files from the OpenEdge library to the Rollbase library. For details on how to
implement OpenEdge authentication in Rollbase, see Configuring OpenEdge Authentication on page
852.
• Basic Authentication — Specifies that the login credentials you create be used to access the service
URI. If you select this option, you must specify the Login Name and Password you want to use to
access Rollbase.
6. Click Next. Rollbase displays the components defined in the OpenEdge Data Service Catalog.
Note: Rollbase will open the catalog and find appropriate REST services that can be mapped to Rollbase
external objects. Only single-table data sets can map to a Rollbase external object. If a JSDO catalog
contains many resources, you can import all available single-table resources at once or you can select them
one at a time to import them.
7. Select the components you want to use from the Select Components area and click Next.
The new object's details are displayed and the default values are inferred from the OpenEdge Data Service
Catalog.
8. Accept or edit the default values, and for each object you create, specify the fields that should be used as
the Primary Key.
9. Click Create to create the objects.
Creating an application from OpenEdge data
You can create the foundation data model for a Rollbase application (multiple objects) with data from OpenEdge
Object Services. You do this by specifying an OpenEdge Data Service Catalog file and an OpenEdge URI
when you create the application.
To create a Rollbase application from an OpenEdge Object Service:
1. Do one of the following:
• From an application page: Select New Application from the Rollbase menu.
• From a setup page: Click New Application on the sidebar.
2. Select Create from External Data.
The Import Application Metadata page opens.
3. Select OpenEdge Service and click Next.
The Import an Application from OpenEdge Services page opens.
4. Specify the following:
If you are using Hosted Rollbase:
588 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Creating Rollbase objects from OpenEdge Object Services
• OpenEdge JSDO Catalog — The OpenEdge Data Service Catalog file. Progress recommends that you
refer to the Enabling support for filtering options and sorting on page 590 to learn what a Data Service
Catalog must include to fully use Rollbase functionality.
• Service URI — The URI for the Web application where the OpenEdge Data Object Service is deployed
• No Authentication — Specifies that no login credentials are required to access the service URI
• Basic Authentication — Specifies that the login credentials you create be used to access the service
URI. If you select this option, you must specify the Login Name and Password you want to use to
access Rollbase.
If you are using Rollbase Private Cloud:
• OpenEdge JSDO Catalog — The OpenEdge Data Service Catalog file. Progress recommends that you
refer to the Enabling support for filtering options and sorting on page 590 to learn what a Data Service
Catalog must include to fully use Rollbase functionality.
• Service URI — The URI for the Web application where the OpenEdge Data Object Service is deployed
• No Authentication — Specifies that no login credentials are required to access the service URI
• Use Current User (if OpenEdge Authentication is enabled) — Specifies that OpenEdge credentials
are required to access the service URI. This is the default option for users accessing Rollbase using
OpenEdge credentials and this option is not available for non-OpenEdge users.
Note: If the OpenEdge service is configured with single point authentication, Rollbase must also have
OpenEdge authentication configured for it, and as a prerequisite, you (a Private Cloud user) must copy
a set of JAR files from the OpenEdge library to the Rollbase library. For details on how to implement
OpenEdge authentication in Rollbase, see Configuring OpenEdge Authentication on page 852.
• Basic Authentication: Specifies that the login credentials you create be used to access the service
URI. If you select this option, you must specify Login Name and Password of your choice that you want
to use to access Rollbase.
5. Click Next. The Import an Application from OpenEdge Services page is updated to show the components
defined in the OpenEdge JSDO Catalog.
6. Select the objects you want to import and click Next.
The Import an Application from OpenEdge Services page is updated to show the application's details.
The default values for the application and object names are inferred from the OpenEdge JSDO Catalog.
7. Select Do you want to create a new Tab for the object now to add a tab for your object and Service
object support complex filter and sorting to enable sorting and filtering of fields when viewing application
data. Accept the default values or modify them as per your requirements.
Note: For each object you create, you must have only one field specified as the Record Name field, and
for each object that you create, specify the fields that should be used as the Primary Key. Neglecting this
step will mean that some Rollbase capabilities that rely on finding triggers or related objects cannot be used.
8. Click Create.
The application is created and added to the list of existing application.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 589
Chapter 9: Integrating with outside sources
Enabling support for filtering options and sorting
This topic describes how to enable support for filtering options and sorting in OpenEdge.
In OpenEdge, you create one or more Business Entities as Data Object resources and generate your Data
Service Catalog when you create the Data Object Service from these resources. A Business Entity is an ABL
class or procedure object that implements a service interface that provides client access to data and business
logic running on an OpenEdge application server. In Rollbase, you use the Data Service Catalog to create
Rollbase external objects associated with OpenEdge Data Objects. You can enable support for filtering options
and sorting by enhancing the Business Entity to accept a JSON object (JSON Filter Pattern) as a filter parameter.
This section describes what you must include in your Business Entity to enable sorting and filtering options in
Rollbase.
To support sorting and filtering, you must ensure that your Business Entity and the associated include file (.i)
with the schema has support for the parameters that are contained in the JSON object:
• ablfilter — Supports filtering of records
• id — Supports search by ID
• top and skip — Supports paging
• orderby — Supports sorting and grouping of records
In the include file, the temp-table definitions include the fields id and sequence (seq) to support JSON filter:
• The id field is used to support the id parameter in the JSON filter.
• The seq field is used to support the orderby parameter in the JSON filter.
The Read operation method method contains the code to process the JSON filter and return the corresponding
records. The code uses the JSON classes in ABL to process the JSON filter. The ABL code implements the
logic to handle each parameter. An AFTER-ROW-FILL method callback is used to populate the values of the
id and seq fields. The local variable iSeq is used to obtain the values for the seq field.
Note: When you use the following code samples, verify that the formatting of the code is maintained.
Alternatively, you can download the code samples from a Progress Community page.
The following sample include file (customer.i) illustrates a temp-table definition with id and seq fields:
/*------------------------------------------------------------------------
File : customer.i
Purpose :
Syntax :
Description :
Author(s) :
Created :
Notes :
----------------------------------------------------------------------*/
/* *************************** Definitions ************************** */
/* ******************** Preprocessor Definitions ******************** */
/* *************************** Main Block *************************** */
/** Dynamically generated schema file **/
@openapi.openedge.entity.primarykey (fields="CustNum").
DEFINE TEMP-TABLE ttCustomer BEFORE-TABLE bttCustomer
FIELD id AS CHARACTER
FIELD seq AS INTEGER INITIAL ?
590 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Creating Rollbase objects from OpenEdge Object Services
FIELD CustNum AS INTEGER INITIAL "0" LABEL "Cust Num"
FIELD Name AS CHARACTER LABEL "Name"
FIELD Address AS CHARACTER LABEL "Address"
FIELD Address2 AS CHARACTER LABEL "Address2"
FIELD Balance AS DECIMAL INITIAL "0" LABEL "Balance"
FIELD City AS CHARACTER LABEL "City"
FIELD Comments AS CHARACTER LABEL "Comments"
FIELD Contact AS CHARACTER LABEL "Contact"
FIELD Country AS CHARACTER INITIAL "USA" LABEL "Country"
FIELD CreditLimit AS DECIMAL INITIAL "1500" LABEL "Credit Limit"
FIELD Discount AS INTEGER INITIAL "0" LABEL "Discount"
FIELD EmailAddress AS CHARACTER LABEL "Email"
FIELD Fax AS CHARACTER LABEL "Fax"
FIELD Phone AS CHARACTER LABEL "Phone"
FIELD PostalCode AS CHARACTER LABEL "Postal Code"
FIELD SalesRep AS CHARACTER LABEL "Sales Rep"
FIELD State AS CHARACTER LABEL "State"
FIELD Terms AS CHARACTER INITIAL "Net30" LABEL "Terms"
INDEX seq seq
.
DEFINE DATASET dsCustomer FOR ttCustomer.
In the OpenEdge Business Entity, the code to process the JSON Filter Pattern is called from the read method
and replaces the generated code for the read method as well as the private applyFillMethod() method.
The following business entity code from OpenEdge illustrates how to process the JSON Filter Pattern and
enable filtering and sorting:
/*------------------------------------------------------------------------
File : Customer.cls
Syntax :
Author(s) :
Created :
Notes :
----------------------------------------------------------------------*/
@program FILE(name="Customer.cls", module="AppServer").
@openapi.openedge.export FILE(type="REST", executionMode="singleton",
useReturnValue="false", writeDataSetBeforeImage="false").
@progress.service.resource FILE(name="Customer", URI="/Customer", schemaName="dsCustomer",
schemaFile="").
USING Progress.Lang.*.
USING Progress.Json.ObjectModel.*.
BLOCK-LEVEL ON ERROR UNDO, THROW.
CLASS Customer:
/*------------------------------------------------------------------------------
Purpose:
Notes:
------------------------------------------------------------------------------*/
{"customer.i"}
DEFINE DATA-SOURCE srcCustomer FOR Customer.
DEFINE VARIABLE iSeq AS INTEGER NO-UNDO.
/*------------------------------------------------------------------------------
Purpose: Get one or more records, based on a filter string
Notes:
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 591
Chapter 9: Integrating with outside sources
------------------------------------------------------------------------------*/
@openapi.openedge.export(type="REST", useReturnValue="false",
writeDataSetBeforeImage="false").
@progress.service.resourceMapping(type="REST", operation="read",
URI="?filter=~{filter~}", alias="", mediaType="application/json").
METHOD PUBLIC VOID ReadCustomer(
INPUT filter AS CHARACTER,
OUTPUT DATASET dsCustomer):
DEFINE VARIABLE jsonParser AS ObjectModelParser NO-UNDO.
DEFINE VARIABLE jsonObject AS JsonObject NO-UNDO.
DEFINE VARIABLE cWhere AS CHARACTER NO-UNDO.
DEFINE VARIABLE hQuery AS HANDLE NO-UNDO.
DEFINE VARIABLE lUseReposition AS LOGICAL NO-UNDO.
DEFINE VARIABLE iCount AS INTEGER NO-UNDO.
DEFINE VARIABLE ablFilter AS CHARACTER NO-UNDO.
DEFINE VARIABLE id AS CHARACTER INITIAL ? NO-UNDO.
DEFINE VARIABLE iMaxRows AS INTEGER INITIAL ? NO-UNDO.
DEFINE VARIABLE iSkipRows AS INTEGER INITIAL ? NO-UNDO.
DEFINE VARIABLE cOrderBy AS CHARACTER INITIAL "" NO-UNDO.
/* The filter parameter can be:
- a WHERE clause: if it begins with WHERE
- a JSON object representing a query if it begins with {
- a free form filter specific to the business entity
*/
MESSAGE "DEBUG: " filter.
/* get rid of any existing data */
EMPTY TEMP-TABLE ttCustomer.
iSeq = 0.
IF filter BEGINS "WHERE " THEN
cWhere = filter.
ELSE IF filter BEGINS "~{" THEN
DO:
jsonParser = NEW ObjectModelParser().
jsonObject = CAST(jsonParser:Parse(filter), jsonObject).
iMaxRows = jsonObject:GetInteger("top") NO-ERROR.
iSkipRows = jsonObject:GetInteger("skip") NO-ERROR.
ablFilter = jsonObject:GetCharacter("ablFilter") NO-ERROR.
id = jsonObject:GetCharacter("id") NO-ERROR.
cOrderBy = jsonObject:GetCharacter("orderBy") NO-ERROR.
cWhere = "WHERE " + ablFilter.
IF cOrderBy > "" THEN
DO:
cOrderBy = REPLACE(cOrderBy, ",", " by ").
cOrderBy = "by " + cOrderBy + " ".
/* NOTE: id and seq fields should be removed from cWhere and cOrderBy
*/
cOrderBy = REPLACE(cOrderBy, "by id desc", "").
cOrderBy = REPLACE(cOrderBy, "by id ", "").
cOrderBy = REPLACE(cOrderBy, "by seq desc", "").
cOrderBy = REPLACE(cOrderBy, "by seq ", "").
END.
lUseReposition = iSkipRows <> ?.
END.
ELSE IF filter NE "" THEN
DO:
/* Use filter as WHERE clause */
cWhere = "WHERE " + filter.
592 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Creating Rollbase objects from OpenEdge Object Services
END.
IF iMaxRows <> ? AND iMaxRows > 0 THEN
DO:
BUFFER ttCustomer:HANDLE:BATCH-SIZE = iMaxRows.
END.
ELSE DO:
IF id > "" THEN
BUFFER ttCustomer:HANDLE:BATCH-SIZE = 1.
ELSE
BUFFER ttCustomer:HANDLE:BATCH-SIZE = 0.
END.
BUFFER ttCustomer:ATTACH-DATA-SOURCE(DATA-SOURCE srcCustomer:HANDLE).
IF cOrderBy = ? THEN cOrderBy = "".
cWhere = IF cWhere > "" THEN (cWhere + " " + cOrderBy) ELSE ("WHERE " + cOrderBy).
MESSAGE "DEBUG: cWhere: " cWhere.
MESSAGE "DEBUG: cOrderBy: " cOrderBy.
DATA-SOURCE srcCustomer:FILL-WHERE-STRING = cWhere.
IF lUseReposition THEN
DO:
hQuery = DATA-SOURCE srcCustomer:QUERY.
hQuery:QUERY-OPEN.
IF id > "" AND id <> "?" THEN
DO:
hQuery:REPOSITION-TO-ROWID(TO-ROWID(id)).
END.
ELSE IF iSkipRows <> ? AND iSkipRows > 0 THEN
DO:
hQuery:REPOSITION-TO-ROW(iSkipRows).
IF NOT AVAILABLE Customer THEN
hQuery:GET-NEXT () NO-ERROR.
END.
iCount = 0.
REPEAT WHILE NOT hQuery:QUERY-OFF-END AND iCount < iMaxRows:
hQuery:GET-NEXT () NO-ERROR.
IF AVAILABLE Customer THEN
DO:
CREATE ttCustomer.
BUFFER-COPY Customer TO ttCustomer.
ASSIGN ttCustomer.id = STRING(ROWID(Customer))
iSeq = iSeq + 1
ttCustomer.seq = iSeq.
END.
iCount = iCount + 1.
END.
END.
ELSE DO:
IF id > "" THEN DATA-SOURCE srcCustomer:RESTART-ROWID(1) = TO-ROWID ((id)).
BUFFER ttCustomer:SET-CALLBACK ("AFTER-ROW-FILL", "AddIdField").
DATASET dsCustomer:FILL().
END.
FINALLY:
BUFFER ttCustomer:DETACH-DATA-SOURCE().
END FINALLY.
END METHOD.
METHOD PUBLIC VOID AddIdField (INPUT DATASET dsCustomer):
ASSIGN ttCustomer.id = STRING(ROWID(Customer))
iSeq = iSeq + 1
ttCustomer.seq = iSeq.
END.
/*------------------------------------------------------------------------------
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 593
Chapter 9: Integrating with outside sources
Purpose: Create one or more new records
Notes:
------------------------------------------------------------------------------*/
@openapi.openedge.export(type="REST", useReturnValue="false",
writeDataSetBeforeImage="false").
@progress.service.resourceMapping(type="REST", operation="create", URI="", alias="",
mediaType="application/json").
METHOD PUBLIC VOID CreateCustomer(INPUT-OUTPUT DATASET dsCustomer):
THIS-OBJECT:CommitCustomer(INPUT "", INPUT ROW-CREATED).
RETURN.
END METHOD.
/*------------------------------------------------------------------------------
Purpose: Update one or more records
Notes:
------------------------------------------------------------------------------*/
@openapi.openedge.export(type="REST", useReturnValue="false",
writeDataSetBeforeImage="false").
@progress.service.resourceMapping(type="REST", operation="update", URI="", alias="",
mediaType="application/json").
METHOD PUBLIC VOID UpdateCustomer(INPUT-OUTPUT DATASET dsCustomer):
THIS-OBJECT:CommitCustomer(INPUT "", INPUT ROW-MODIFIED).
END METHOD.
/*------------------------------------------------------------------------------
Purpose: Delete a record
Notes:
------------------------------------------------------------------------------*/
@openapi.openedge.export(type="REST", useReturnValue="false",
writeDataSetBeforeImage="false").
@progress.service.resourceMapping(type="REST", operation="delete", URI="", alias="",
mediaType="application/json").
METHOD PUBLIC VOID DeleteCustomer(INPUT-OUTPUT DATASET dsCustomer):
THIS-OBJECT:CommitCustomer(INPUT "", INPUT ROW-DELETED).
END METHOD.
/*------------------------------------------------------------------------------
Purpose: generic routine for creating/updating/deleting customers
Notes:
------------------------------------------------------------------------------*/
METHOD PRIVATE VOID commitCustomer(
INPUT pcFieldMapping AS CHARACTER,
INPUT piRowState AS INTEGER ):
DEFINE VARIABLE Skip-list AS CHAR NO-UNDO.
BUFFER ttCustomer:ATTACH-DATA-SOURCE (DATA-SOURCE srcCustomer:HANDLE,
pcFieldMapping).
FOR EACH ttCustomer.
BUFFER ttCustomer:MARK-ROW-STATE (piRowState).
END.
IF piRowState = ROW-CREATED THEN
Skip-list = "CustNum".
FOR EACH bttCustomer:
BUFFER bttCustomer:SAVE-ROW-CHANGES(1, Skip-list).
END.
FINALLY:
594 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Creating Rollbase objects from OpenEdge Object Services
BUFFER ttCustomer:DETACH-DATA-SOURCE().
RETURN.
END FINALLY.
END METHOD.
END CLASS.
In a Business Entity from the latest release of OpenEdge, you can enable filtering and sorting by replacing the
code in the Read method with the code that processes the JSON filter in a similar way to the above code, which
continues to work in OpenEdge 11.3 or greater.
The following are additional annotations required for this use case in OpenEdge 11.5.1 and 11.6. They must
be added manually.
@openapi.openedge.method.property(name="mappingType", value="JFP").
@openapi.openedge.method.property (name="capabilities",
value="ablFilter,top,skip,id,orderBy").
Note: The ablFilter parameter is considered to always be supported and does not need to be listed in the
values for the capabilities property.
The following is a Business Entity class file from OpenEdge that contains the code to process the JSON Filter
Pattern:
/*------------------------------------------------------------------------
File : Customer.cls
Syntax :
Author(s) :
Created :
Notes :
----------------------------------------------------------------------*/
@program FILE(name="Customer.cls", module="AppServer").
@openapi.openedge.export FILE(type="REST", executionMode="singleton",
useReturnValue="false", writeDataSetBeforeImage="false").
@progress.service.resource FILE(name="Customer", URI="/Customer", schemaName="dsCustomer",
schemaFile="Test/AppServer/customer.i").
USING OpenEdge.BusinessLogic.BusinessEntity.
USING Progress.Lang.*.
USING Progress.Json.ObjectModel.*.
BLOCK-LEVEL ON ERROR UNDO, THROW.
CLASS Customer INHERITS BusinessEntity:
/*------------------------------------------------------------------------------
Purpose:
Notes:
------------------------------------------------------------------------------*/
{"customer.i"}
DEFINE DATA-SOURCE srcCustomer FOR sports2000.Customer.
DEFINE VARIABLE iSeq AS INTEGER NO-UNDO.
/*------------------------------------------------------------------------------
Purpose:
Notes:
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 595
Chapter 9: Integrating with outside sources
------------------------------------------------------------------------------*/
CONSTRUCTOR PUBLIC Customer():
DEFINE VAR hDataSourceArray AS HANDLE NO-UNDO EXTENT 1.
DEFINE VAR cSkipListArray AS CHAR NO-UNDO EXTENT 1.
SUPER (DATASET dsCustomer:HANDLE).
/* Data Source for each table in dataset. Should be in table order as defined
in DataSet */
hDataSourceArray[1] = DATA-SOURCE srcCustomer:HANDLE.
/* Skip-list entry for each table in dataset. Should be in temp-table order
as defined in DataSet */
/* Each skip-list entry is a comma-separated list of field names, to be
ignored in create stmt */
cSkipListArray[1] = "CustNum".
THIS-OBJECT:ProDataSource = hDataSourceArray.
THIS-OBJECT:SkipList = cSkipListArray.
END CONSTRUCTOR.
/*------------------------------------------------------------------------------
Purpose: Get one or more records, based on a filter string
Notes:
------------------------------------------------------------------------------*/
@openapi.openedge.export(type="REST", useReturnValue="false",
writeDataSetBeforeImage="true").
@progress.service.resourceMapping(type="REST", operation="read",
URI="?filter=~{filter~}", alias="", mediaType="application/json").
@openapi.openedge.method.property (name="capabilities", value="top,skip,id,orderBy").
METHOD PUBLIC VOID ReadCustomer(
INPUT filter AS CHARACTER,
OUTPUT DATASET dsCustomer):
DEFINE VARIABLE jsonParser AS ObjectModelParser NO-UNDO.
DEFINE VARIABLE jsonObject AS JsonObject NO-UNDO.
DEFINE VARIABLE cWhere AS CHARACTER NO-UNDO.
DEFINE VARIABLE hQuery AS HANDLE NO-UNDO.
DEFINE VARIABLE lUseReposition AS LOGICAL NO-UNDO.
DEFINE VARIABLE iCount AS INTEGER NO-UNDO.
DEFINE VARIABLE ablFilter AS CHARACTER NO-UNDO.
DEFINE VARIABLE id AS CHARACTER INITIAL ? NO-UNDO.
DEFINE VARIABLE iMaxRows AS INTEGER INITIAL ? NO-UNDO.
DEFINE VARIABLE iSkipRows AS INTEGER INITIAL ? NO-UNDO.
DEFINE VARIABLE cOrderBy AS CHARACTER INITIAL "" NO-UNDO.
/* The filter parameter can be:
- a WHERE clause: if it begins with WHERE
- a JSON object representing a query if it begins with {
- a free form filter specific to the business entity
*/
MESSAGE "DEBUG: " filter.
/* get rid of any existing data */
596 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Creating Rollbase objects from OpenEdge Object Services
EMPTY TEMP-TABLE ttCustomer.
iSeq = 0.
IF filter BEGINS "WHERE " THEN
cWhere = filter.
ELSE IF filter BEGINS "~{" THEN
DO:
jsonParser = NEW ObjectModelParser().
jsonObject = CAST(jsonParser:Parse(filter), jsonObject).
iMaxRows = jsonObject:GetInteger("top") NO-ERROR.
iSkipRows = jsonObject:GetInteger("skip") NO-ERROR.
ablFilter = jsonObject:GetCharacter("ablFilter") NO-ERROR.
id = jsonObject:GetCharacter("id") NO-ERROR.
cOrderBy = jsonObject:GetCharacter("orderBy") NO-ERROR.
cWhere = "WHERE " + ablFilter.
IF cOrderBy > "" THEN
DO:
cOrderBy = REPLACE(cOrderBy, ",", " by ").
cOrderBy = "by " + cOrderBy + " ".
/* NOTE: id and seq fields should be removed from cWhere and cOrderBy
*/
cOrderBy = REPLACE(cOrderBy, "by id desc", "").
cOrderBy = REPLACE(cOrderBy, "by id ", "").
cOrderBy = REPLACE(cOrderBy, "by seq desc", "").
cOrderBy = REPLACE(cOrderBy, "by seq ", "").
END.
lUseReposition = iSkipRows <> ?.
END.
ELSE IF filter NE "" THEN
DO:
/* Use filter as WHERE clause */
cWhere = "WHERE " + filter.
END.
IF iMaxRows <> ? AND iMaxRows > 0 THEN
DO:
BUFFER ttCustomer:HANDLE:BATCH-SIZE = iMaxRows.
END.
ELSE DO:
IF id > "" THEN
BUFFER ttCustomer:HANDLE:BATCH-SIZE = 1.
ELSE
BUFFER ttCustomer:HANDLE:BATCH-SIZE = 0.
END.
BUFFER ttCustomer:ATTACH-DATA-SOURCE(DATA-SOURCE srcCustomer:HANDLE).
IF cOrderBy = ? THEN cOrderBy = "".
cWhere = IF cWhere > "" THEN (cWhere + " " + cOrderBy) ELSE ("WHERE " + cOrderBy).
MESSAGE "DEBUG: cWhere: " cWhere.
MESSAGE "DEBUG: cOrderBy: " cOrderBy.
DATA-SOURCE srcCustomer:FILL-WHERE-STRING = cWhere.
IF lUseReposition THEN
DO:
hQuery = DATA-SOURCE srcCustomer:QUERY.
hQuery:QUERY-OPEN.
IF id > "" AND id <> "?" THEN
DO:
hQuery:REPOSITION-TO-ROWID(TO-ROWID(id)).
END.
ELSE IF iSkipRows <> ? AND iSkipRows > 0 THEN
DO:
hQuery:REPOSITION-TO-ROW(iSkipRows).
IF NOT AVAILABLE Customer THEN
hQuery:GET-NEXT () NO-ERROR.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 597
Chapter 9: Integrating with outside sources
END.
iCount = 0.
REPEAT WHILE NOT hQuery:QUERY-OFF-END AND iCount < iMaxRows:
hQuery:GET-NEXT () NO-ERROR.
IF AVAILABLE Customer THEN
DO:
CREATE ttCustomer.
BUFFER-COPY Customer TO ttCustomer.
ASSIGN ttCustomer.id = STRING(ROWID(Customer))
iSeq = iSeq + 1
ttCustomer.seq = iSeq.
END.
iCount = iCount + 1.
END.
END.
ELSE DO:
IF id > "" THEN DATA-SOURCE srcCustomer:RESTART-ROWID(1) = TO-ROWID ((id)).
BUFFER ttCustomer:SET-CALLBACK ("AFTER-ROW-FILL", "AddIdField").
DATASET dsCustomer:FILL().
END.
FINALLY:
BUFFER ttCustomer:DETACH-DATA-SOURCE().
END FINALLY.
END METHOD.
METHOD PUBLIC VOID AddIdField (INPUT DATASET dsCustomer):
ASSIGN ttCustomer.id = STRING(ROWID(Customer))
iSeq = iSeq + 1
ttCustomer.seq = iSeq.
END.
/*------------------------------------------------------------------------------
Purpose: Create one or more new records
Notes:
------------------------------------------------------------------------------*/
@openapi.openedge.export(type="REST", useReturnValue="false",
writeDataSetBeforeImage="true").
@progress.service.resourceMapping(type="REST", operation="create", URI="", alias="",
mediaType="application/json").
METHOD PUBLIC VOID CreateCustomer(INPUT-OUTPUT DATASET dsCustomer):
DEFINE VAR hDataSet AS HANDLE NO-UNDO.
hDataSet = DATASET dsCustomer:HANDLE.
SUPER:CreateData(DATASET-HANDLE hDataSet BY-REFERENCE).
END METHOD.
/*------------------------------------------------------------------------------
Purpose: Update one or more records
Notes:
------------------------------------------------------------------------------*/
@openapi.openedge.export(type="REST", useReturnValue="false",
writeDataSetBeforeImage="true").
@progress.service.resourceMapping(type="REST", operation="update", URI="", alias="",
mediaType="application/json").
METHOD PUBLIC VOID UpdateCustomer(INPUT-OUTPUT DATASET dsCustomer):
DEFINE VAR hDataSet AS HANDLE NO-UNDO.
hDataSet = DATASET dsCustomer:HANDLE.
SUPER:UpdateData(DATASET-HANDLE hDataSet BY-REFERENCE).
END METHOD.
598 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Creating Rollbase objects from OpenEdge Object Services
/*------------------------------------------------------------------------------
Purpose: Delete a record
Notes:
------------------------------------------------------------------------------*/
@openapi.openedge.export(type="REST", useReturnValue="false",
writeDataSetBeforeImage="true").
@progress.service.resourceMapping(type="REST", operation="delete", URI="", alias="",
mediaType="application/json").
METHOD PUBLIC VOID DeleteCustomer(INPUT-OUTPUT DATASET dsCustomer):
DEFINE VAR hDataSet AS HANDLE NO-UNDO.
hDataSet = DATASET dsCustomer:HANDLE.
SUPER:DeleteData(DATASET-HANDLE hDataSet BY-REFERENCE).
END METHOD.
/*------------------------------------------------------------------------------
Purpose: Submit a record
Notes:
------------------------------------------------------------------------------*/
@openapi.openedge.export(type="REST", useReturnValue="false",
writeDataSetBeforeImage="true").
@progress.service.resourceMapping(type="REST", operation="submit",
URI="/SubmitCustomer", alias="", mediaType="application/json").
METHOD PUBLIC VOID SubmitCustomer(INPUT-OUTPUT DATASET dsCustomer):
/* Calling extending class's CUD methods instead of SUPER:Submit() in case
customized functionality was added.
Do deletes first, next modifies, and finally creates */
THIS-OBJECT:DeleteCustomer(DATASET dsCustomer).
THIS-OBJECT:UpdateCustomer(DATASET dsCustomer).
THIS-OBJECT:CreateCustomer(DATASET dsCustomer).
END METHOD.
END CLASS.
For information about sorting and grouping, see Filtering OpenEdge Service objects by search criteria on page
446.
Enabling object attributes for an OpenEdge Data Object
This topic describes how to enable object attributes in OpenEdge.
In OpenEdge, you create a Business Entity and generate your Data Service Catalog when you create the Data
Object Service from it. A Business Entity is an ABL class or procedure object that implements a service interface
that provides client access to data and business logic running on an OpenEdge application server. In Rollbase,
you use the Data Service Catalog to create Rollbase external objects associated with OpenEdge Data Objects.
For an OpenEdge Data Object to support object attributes, you must code your OpenEdge Business Entity in
a way that includes the fields required to enable the object attributes. For information about object attributes,
see Object attributes on page 79.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 599
Chapter 9: Integrating with outside sources
To enable object attributes for an OpenEdge Data Object:
1. Decide which object attributes you must enable for your OpenEdge Data Object.
2. In OpenEdge, build a Business Entity to implement the Data Object for an ABL temp-table that consists of
the required fields for all the object attributes. This is done using the information provided in the table below.
3. In Rollbase, using a Data Service Catalog that defines the schema for this Data Object, create a Rollbase
external object associated with the OpenEdge Data Object (see Linking Rollbase external objects to
OpenEdge data on page 586).
4. Edit the Rollbase external object definition to include the required object attributes by selecting each object
attribute and mapping the available fields required to set the object attribute.
The following table lists all the object attributes supported in an OpenEdge Data Object and the corresponding
fields required in the Data Service Catalog:
600 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Creating Rollbase objects from OpenEdge Object Services
Object attribute Rollbase fields to map to OpenEdge fields Data type of the field
Workflow Process CHARACTER
Status CHARACTER
Contact First Name CHARACTER
Middle Name CHARACTER
Last Name CHARACTER
Email CHARACTER
Fax CHARACTER
Phone CHARACTER
Location Street Address-1 CHARACTER
Street Address-2 CHARACTER
City CHARACTER
State/Province CHARACTER
Country CHARACTER
Event Event Subject CHARACTER
Duration INT64
Date/Time DATETIME-TZ
Private LOGICAL
Description CHARACTER
Location CHARACTER
Pop-up Reminder CHARACTER
Reminded LOGICAL
Task Task Subject CHARACTER
Due Date DATETIME-TZ
Priority INTEGER
Private LOGICAL
Description CHARACTER
Multi-Currency Currency Code CHARACTER
Rate Date DATE
Lockable Is Locked LOGICAL
Document Document File CHARACTER
Description CHARACTER
You can selectively map the OpenEdge fields in the OpenEdge Data Object resource for a given Rollbase
external object to the corresponding Rollbase fields based on which object attributes you need in your Rollbase
external object. The field names can be of your choice but you must ensure that the number of fields (and their
respective OpenEdge data types) required for enabling an object attribute conforms to the information provided
in the above table. For example, to enable the Multi-Currency object attribute, you must have two available
fields in your Data Object resource (one to store Currency Code and another to store Rate Date).
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 601
Chapter 9: Integrating with outside sources
Example:
To enable the Workflow attribute for your OpenEdge Data Object, add two temp-table fields, such as
PROCESS_ID and STATUS_ID, of CHARACTER data type in your OpenEdge Business Entity. The following is
a section of a Data Service Catalog file (.json) that includes the two example fields:
"version": "1.2",
"lastModified": "Thu Oct 30 03:03:24 PDT 2014",
"services": [{
"name": "WorkflowobjService",
"address": "\/rest\/WorkflowobjService",
.
.
.
"PROCESS_ID": {
"type": "string",
"ablType": "CHARACTER",
"default": "",
"title": "PROCESSID"
},
"STATUS_ID": {
"type": "string",
"ablType": "CHARACTER",
"default": "",
"title": "STATUSID"
},
.
.
.
After you have created a Rollbase external object associated with the OpenEdge Data Object (see Linking
Rollbase external objects to OpenEdge data on page 586), edit your object definition (see Viewing and editing
an Object Definition on page 132) to add the Workflow attribute and map the PROCESS_ID and STATUS_ID
fields to Workflow Process and Workflow Status:
Using DataDirect Cloud to access external data
DataDirect Cloud simplifies access to cloud data sources such as applications hosted on cloud platforms like
Salesforce.com and Eloqua. You can use external objects together with DataDirect Cloud to easily bring external
data into your Rollbase application. Watch a video for a quick overview.
602 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Using DataDirect Cloud to access external data
Each external object maps to a table in the external data source. Before you can follow these procedures, you
must have used DataDirect Cloud to create and test a Data Source definition for the target data source. Before
creating the external object in Rollbase, determine the Data Source definition name, whether the credentials
are stored in the Data Source definition, and whether your data source is case-sensitive with respect to table
and column names. You will need this information when creating the external object.
To create an external object that uses DataDirect Cloud to access data in an external source:
1. Navigate to the target application.
2. Click + on the application menu bar.
3. Select A new Object (with tab) from an External Metadata.
4. Click Create.
The Import Object Metadata page opens.
5. For Import Object Metadata, select DataDirect Cloud. Click Create.
The Import from DataDirect Cloud page opens.
6. On the Import from DataDirect Cloud page, specify the following:
• The login name and password for your DataDirect Cloud account.
• The name of the Data Source definition to use for connection. (The definition must already existing in
your DataDirect Cloud account.)
• Table and column names are case sensitive — select this checkbox to enable case sensitivity.
• Prompt for individual user credentials to access target Data Source — select this checkbox if the
credentials for this data source are not stored in the DataDirect Cloud Data Source definition.
7. Click Next.
The Create Object page opens.
8. From the Select Table drop-down, choose one of the available tables.
9. Enter values for the object name and set the desired permissions.
10. Click Create Object.
The Create Fields page opens:
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 603
Chapter 9: Integrating with outside sources
11. Select the columns to use for creating the object's primary key and the options to create the object's fields.
12. Click Create Fields.
13. Select the appropriate Rollbase type and if desired, edit the label and integration names.
14. Click Create Fields.
The Adjust SQL page opens.
15. Click Preview Query to see what the external object will look like.
16. If the preview is not as expected, edit the SQL query and try again.
17. When you are satisfied with the results, click Save.
Rollbase creates an object similar to an external database object, but with the following limitations:
• Related application features are disabled
• Only SELECT queries will be sent
• Relationships involving external objects support only the following scenarios:
• 1-1 or 1-N cardinality when establishing a relationship between an external object and another external
object or a Rollbase Native object.
• 1-1 or N-1 cardinality when establishing a relationship between a Rollbase native object and an
external object.
Note that if you checked the Prompt for individual user credentials check box, every user will need to
enter credentials each time they log in. These are not the DataDirect Cloud credentials, but credentials for
the data source, such as Salesforce, Eloqua, or Hubspot.
604 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Calling Progress Corticon decision services from Rollbase
Calling Progress Corticon decision services from
Rollbase
You can call Progress Corticon decision services from Rollbaseusing the Corticon Decision Service trigger
type.
See Automating business decisions with Corticon rules on page 277 for more information.
Creating a Rollbase application from Microsoft Access
The topics in this section explain how to create an entire Rollbase application by uploading a Microsoft Access
Database format (MDB) file.
See the following topics for instructions and an example:
• Uploading the MDB file on page 605
• Creating objects from MDB tables on page 606
• Mapping fields and creating records on page 607
• Reviewing results on page 611
Uploading the MDB file
To upload an MDB file:
1. Do one of the following:
• From an application page: Select New Application from the Rollbase menu.
• From a setup page: Click New Application on the sidebar.
The Create a New Application dialog opens.
2. Click Create from External Data. The Import Application Metadata page opens.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 605
Chapter 9: Integrating with outside sources
3. Click Convert MS Access Database and click Next. The Upload Database page opens. The file size
cannot exceed 50MB; please contact Rollbase support if you need to upload a larger file.
Note: The file size limit is configurable. However. the file size limit 50MB is set for Rollbase Public Cloud.
4. Browse to the MDB file and click Next. The Create Objects page opens.
Note: The Rollbase conversion tool does not support MDB formats older than Access 2000.
Creating objects from MDB tables
Rollbase reads the structure of the uploaded MDB database. Each table in the MDB database can be converted
into a new Rollbase object and every row in that table can be converted into a Rollbase record. The wizard-style
UI will assist you with these tasks.
To create Rollbase objects from MDB tables:
1. Enter the name for the new application. By default, Rollbase uses the name of the uploaded database.
2. Select which tables should be converted into Rollbase objects. Select singular and plural names for these
objects (the table's name is used by default). Rollbase displays the number of records in the uploaded
database for each table for informational purposes. Rollbase reads the metadata for the database and
creates a primary key for each object. Rollbase also reads each table description in the database and saves
it as the object description.
3. Optionally select Rollbase attributes for the newly created objects. Progress recommends using the Contact
attribute for tables that represent people, the Location attribute for tables that represent things with a
physical/geographical address, and the Workflow attribute for objects which will be involved in workflow
processes. See Object attributes on page 79 for more information about attributes.
4. From the Name Column column, select any column with a string data type to use for the Record Name
field. Rollbase includes the Record Name field in the default view it creates for the object; users click the
Record Name field to navigate to the object's View page. If an object does not have a Record Name field,
imported records will not have a distinguishable name. For tables that represent people, and for which you
will add the Contact attribute, leave this value at its default. Rollbase will automatically create a Record
Name field that includes the First Name and Last Name values.
5. Select the objects for which you want to create associated tabs. Typically, every standalone object (except
for dependent ones) should have an associated tab.
For example, the resulting configuration for the Northwind database is shown below. Note that the dependent
object Order Details has a composite primary key and does not have an associated tab. Some objects have
attributes assigned to them; for example, the Employee object has the Contact and Location attributes, the
Customer object has the Location attribute, and the Order object has the Workflow attribute. See Object
attributes on page 79 for more information about available attributes.
606 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Creating a Rollbase application from Microsoft Access
Click Create Objects to create eight Rollbase objects and seven tabs in an application called Northwind. The
next step is to map fields from the database to Rollbase objects.
Mapping fields and creating records
At this point, each selected database table has an associated Rollbase object. The next step is to tell Rollbase
what to do with the tables' columns. For each column, you can choose from one of the following:
• Create a new Rollbase field. Use this option when mapping to a field where there is no existing field
corresponding to the column in the Rollbase object.
• Map a column to an existing Rollbase field. Use this option when mapping to a field included with an attribute.
For example, the Location attribute contains fields such as City, Country, and ZIP/Postal Code.
• Discard the column. Use this option if you do not want to include the column as a field in the object.
Rollbase reads the metadata from the database and automatically does the following:
• Marks fields that must have a unique value in the Unique Column column. These fields will include the Do
not allow duplicate values in this field property.
• Creates a Unique Fields Combination trigger for each multi-column unique key in the database that
includes all fields in the index.
• Creates relationships from foreign keys.
Note the following when mapping fields:
• By default, Rollbase derives the name of each field from the corresponding column name and puts that
value in the Label column. You can edit the name. If you are mapping a column to an existing field, edit the
name before selecting the field.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 607
Chapter 9: Integrating with outside sources
• Although the type for a new field is selected by default, you do not have to accept it. Sometimes a different
type (Currency or Text Area) is more appropriate.
• Rollbase maps AutoNumber fields to Auto-Number fields and preserves the values from database rows.
• You can map Hyperlink fields to URL fields.
• You can map Attachment fields to File Upload or Image Upload fields. Rollbase only supports a single
attachment; if a database row has an array of attachments, Rollbase uses only the first attachment from
the array.
• You can map OLE objects to File Upload or Image Upload fields. Rollbase supports basic image types
(JPG, GIF, PNG, TIFF, BMP), TXT, and ZIP files. Rollbase does not support Excel, PowerPoint, Word, or
PDF files.
• Rollbase checks for the maximum number of fields allowed for each data type and you will get an error
message when trying to save the mappings if any maximum is exceeded. You can then change data types
and/or discard some columns from the affected tables.
It is always a good idea to double-check your mappings before proceeding with the data import.
The following screens show example mappings for the Customers and Order Details objects. Note the following
about the mappings:
• Customer ID is marked as a Unique Column for the Customer object.
• Some columns are mapped to existing Location fields, such as City and Country..
• The Customer object has one column mapped to the Record Name field. Order Details, which is a
dependent object with no tab, does not have a column mapped to the Record Name field.
• Information about each object's primary key is included at the bottom of each set of mappings. Because
Order Details has a multi-column primary key, there will be a Unique Fields Combination trigger for that
object.
• For the Order Details object, Rollbase automatically creates the relationships to the Order and Product
objects based on foreign keys in the database.
608 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Creating a Rollbase application from Microsoft Access
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 609
Chapter 9: Integrating with outside sources
When you are finished mapping fields, click Create Fields. Rollbase will create the fields as directed and import
data from the database into object records. When the import is complete, Rollbase will send you an email:
610 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Creating a Rollbase application from Microsoft Access
Reviewing results
After the import is complete, you can navigate through the new application's application pages and setup pages
to see the results. You can use the fully functional Rollbase application that preserves both structure and data
from the MDB database.
Relationships between records are preserved as shown below, where a Product has a relationship to a Supplier
and to multiple Order Details:
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 611
Chapter 9: Integrating with outside sources
You can navigate to the Relationships table on the Product object definition page to see the definitions of
the above relationships:
For objects with the Contact attribute, such as Employee in this example, Rollbase created a Record Name
field using the First Name and Last Name fields as shown in the screen below:
612 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Creating a Rollbase application from a Salesforce application
You can navigate to the Employee object definition page to see the Record Name Template Rollbase created
for the Record Name field, the attributes you selected for the object, and other information:
Creating a Rollbase application from a Salesforce
application
In a matter of minutes, you can create a new Rollbase application by migrating an existing Salesforce.com
CRM instance, or by migrating any other application built on the Force.com platform, along with all of its data.
The migrated application will include:
• Object definitions (including fields)
• Object menus
• Relationships between imported objects
• Pages (including sections and related lists)
Note: Because Rollbase and Salesforce.com use different languages for formulas, you will need to substantially
re-write formulas after completion of the migration process. Only in the simplest cases can formulas be used
as-is.
For a video demonstration of migrating applications from Salesforce.com and the Force.com platform see
http://www.rollbase.com/deforce.shtml.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 613
Chapter 9: Integrating with outside sources
Note: Salesforce.com limits number of API calls a particular customer can make in 24 hours span. If you're
receiving REQUEST_LIMIT_EXCEEDED error that means that your limit has been exceeded during the import
process. In this case, the Salesforce limit must be reset before retrying.
Migrating the application
Rollbase uses Web service APIs to extract information from your Salesforce.com or Force.com account. The
migration process builds a new Rollbase application that contains all of your data. Before attempting migration,
ensure that your organization has access to Salesforce.com APIs.
1. Before creating the new application in Rollbase, log in to your Salesforce or Force account and select the
application you want to migrate (for example, if you want to migrate your Salesforce.com CRM application,
be sure to select the "Sales" application). Rollbase migrates the currently active application.
2. Do one of the following:
• From an application page: Select New Application from the Rollbase menu.
• From a setup page: Click New Application on the sidebar.
The Create a New Application dialog opens.
3. Select Create from External Data. The Import Application Metadata page opens.
4. Select Salesforce.com (Force.com) and click Next.
5. Provide your Salesforce.com credentials (Rollbase will not store or reuse your Salesforce.com credentials.
They are only used once to temporarily retrieve your data):
• User name (with sufficient permissions to access Web API)
• Password
• Security token
• To retrieve your Salesforce.com API security token, login to your Salesforce.com account and click
Setup > My Personal Information > Reset Security Token.
6. Rollbase retrieves the following metadata from your most recently accessed Salesforce.com application:
• Object menus (Web and system menus cannot be extracted because Force.com does not expose them
as metadata).
• Custom objects and most standard objects, including their components:
• Field definitions (including formula fields)
• Relationships
• Page layout definitions (which are converted into Rollbase pages)
7. Use the check boxes to identify the objects, fields, and relationships you want to import from Salesforce.com
into your new Rollbase application.
614 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Using external tables as Rollbase objects
Note: If a Salesforce object already exists in your tenant, the migration tool will not attempt to import any
components.
8. Click Create to complete the migration.
After automatically creating and configuring your new application, Rollbase will proceed to import the actual
data from your Salesforce.com account (providing that you've selected this option). The data import is done
asynchronously and you will receive an email with import results when the process is completed. Each call to
Salesforce API brings back up to 500 records of a particular type. Notice that all of your object definitions,
fields, relationships, and data migrated and the exact layout of all of your application pages is maintained in
your new Rollbase application. At this point you can start working with your new application just like any other
Rollbase app, by adding data, editing objects, pages, etc.
Using external tables as Rollbase objects
In Rollbase Private Cloud, external objects allow you to integrate tables managed by other applications into a
Rollbase application. Each external object maps to an external table. External objects have almost all of the
same features as native Rollbase objects, but the data remains stored in the external table rather than in
Rollbase.
For other ways to integrate data using external objects, see Using DataDirect Cloud to access external data
on page 602 or Creating Rollbase objects from OpenEdge Object Services on page 584.
The following topics describe how to use external tables in Rollbase Private Cloud.
Using an external database and external objects for Private Cloud
The Configuring a supported database on page 772 topic explains how to create a fresh Rollbase database by
running the default SQL creation script. If you already have data in an existing database, you can wrap these
existing tables and their data into a Rollbase external object definition. This method allows you to use existing
without impacting the underlying table or any existing applications that rely on it. External database support is
available for MySQL, OpenEdge, DataDirect Cloud, Oracle, and SQL Server databases.
Rollbase tables must reside in the same database where existing tables you want to integrate with reside
because Rollbase transactions are complex and often include multiple updates in several tables. Running these
updates across more than one database has proven to be inefficient. Instead of creating the Rollbase database
tables (schema in Oracle terms) in a new empty database, you will run the default Rollbase SQL creation script
in your existing database that contains the existing tables you want to leverage. The Rollbase SQL creation
script will add 24 new tables, with an RB_ name prefix, without affecting existing tables.
Managing databases on page 832 explains how to describe Rollbase databases in the databases.xml
configuration file. In this way you can have multiple databases for different tenants based on different external
tables you want to integrate this with. Using this approach to describe a new database, add a new XML attribute
isExternal:
<Database name="RB_CUST1" isExternal="yes">..</Database>
Marking a database as external allows for the creation of external objects for Rollbase customer tenants
assigned to that database.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 615
Chapter 9: Integrating with outside sources
External object overview
You can add external objects to applications, publish, and install these applications. Make sure that target
customers have access to the external tables mapped to the external objects. You can edit external objects to
change their name and other properties. External objects and their fields can be configured and used in as
native Rollbase objects, with the following limitations:
• The field creation process is limited as explained in External object fields and attributes on page 616.
• Full text search and search engine indexing is not available for external object fields.
• External records cannot be used as application seed records.
The functionality available for external objects and their fields includes, but is not limited to:
• Configurable pages
• Configurable views
• Detailed search and filtering
• Email and document templates
• Triggers and workflows
• Input validation through triggers and field-level validation
• Reports, charts and gauges
• Unique indexes
• Client-side and server-side API usage
• REST and SOAP APIs
External object fields and attributes
There is a fundamental difference between the way new fields are created for external objects and the way
they are created for native Rollbase objects. In the latter case, new fields can be created either through enabling
a new object attribute (such as Contact or Location) or by creating a field manually in the Rollbase user
interface.
External objects are stored in an existing table with a structure which cannot be modified. For this reason, new
fields in external objects can only be created in one of the following cases:
• They rely on a column in the external table that exists, but has not yet been mapped to a Rollbase field in
that external object.
• They do not require a database column in the external table to store data, such as: formulas, templates,
roll-up Summary, and integration links.
The field configuration process is almost identical to native Rollbase object fields. As usual, newly created
fields on external objects can be added to pages, views, reports, and referenced anywhere normal object fields
can be, such as in formulas, templates, triggers, and validations. Creation or deletion of a field in an external
table will most likely require modifying the SQL queries as described in SQL queries for external objects on
page 618. For your convenience, the system will redirect you to the Adjust SQL page after a field is created or
deleted.
616 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Using external tables as Rollbase objects
You can assign object attributes by mapping fields from particular attribute (such as Contact) to an available
data column. If an attribute box is checked for an external object, all of its fields must be mapped and no column
can be mapped to more than one field. Some fields must be mapped to columns with a specific name. For
example, a workflow Status must be mapped to a column named STATUS_ID.
External relationships
Database tables typically have primary key to foreign key relationships between records. Rollbase can wrap
these relationships the same way as native relationships between objects.
A field of an external object (database column) can serve as a primary key if:
• Its type is text or integer
• It has a "unique value" attribute
When creating fields for new external object, you can select a Foreign Key data type for text or integer database
columns. In this case you need to select a Primary Key too.
If you do not define a relationship when you create the external object, you can do it later. On the object view
page, from the Relationships section, click New External Relationship. Select an unused DB column which
can serve as a foreign key (if any), and select a primary key on another external object. The types of the two
key columns must match. In both cases, the system will create a relationship between two external objects
that works much the same way as normal object relationships. The relationship will be in the form of primary
key to foreign key and only one-to-one and one-to-many relationships are supported.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 617
Chapter 9: Integrating with outside sources
Note that relationships involving external objects support only the following scenarios:
• 1-1 or 1-N cardinality when establishing a relationship between an external object and another external
object or a Rollbase native object
• 1-1 or N-1 cardinality when establishing a relationship between a Rollbase native object and an external
object
SQL queries for external objects
Although Rollbase Private cloud can automatically read the structure of an external table, the actual design of
the external database remains unknown to Rollbase. For this reason, during the process of creating external
objects, you have the option to adjust the SQL queries that Rollbase generates automatically. If Rollbase
experiences a SQL error while working with external objects, an error will be displayed. The Adjust SQL page
allows you to fix those errors by editing the SQL directly. For existing external objects, the Adjust SQL page
is available directly from the More Actions drop-down list on an object view page. If you add or modify a field
for an external object, the Adjust SQL page opens automatically.
To access and manipulate data records in external tables, Rollbase uses SELECT, INSERT, UPDATE, and
DELETE SQL queries. To adjust SQL queries, you must be familiar with SQL, details of your database
implementation, and how Rollbase formulates SQL queries.
618 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Using external tables as Rollbase objects
Note the following about how Rollbase generates and handles an SQL query:
• Rollbase encloses table and column names in double quotes whenever the names contain characters not
recognized as an identifier by SQL syntax or when the names are reserved keywords. This conforms to the
ANSI standards. Therefore, you must ensure that your external database supports double quotes in an SQL
query.
By default, the latest versions of the databases certified by Rollbase support double quotes in queries. If
your database does not support double quotes for tables and column names, then you must configure it to
do so. For example, as MySQL does not support double quotes by default, you must add ANSI to the
comma-separated values of the SQL Mode property.
• If Rollbase encounters an identifier that is not listed as a reserved SQL keyword or a special character in
its Shared Properties, but in reality is an SQL reserved keyword or a special character in your database,
then the SQL query might result in an error because the column or table name will not be enclosed with
double quotes in the SQL query.
In such cases, you must manually edit the SQL query in the Adjust SQL page or add those SQL keywords
and special characters to Shared Properties.
Progress recommends that you verify and add any reserved keywords and special characters in the Shared
Properties before generating SQL queries for External objects. In Shared Properties, you must
locate SQLKeywords and SQLSpecialChars code snippets and then add comma-separated keywords
and special characters respectively. You must restart Rollbase for any update in Shared Properties to
take effect.
You can use stored procedures with parameters to replace the default INSERT, UPDATE, and DELETE SQL
queries. Rollbase will use these queries exactly the way they're provided. However, since SELECT queries
are necessary for filtering and sorting, a SELECT query cannot be replaced with a stored procedure. The query
or stored procedure must fetch an ID for new records. For Oracle databases, the query can include a sequence
to fetch record IDs.
SQL queries must use actual database column names. To supply data to the database, INSERT and UPDATE
queries must use template tokens for Rollbase fields. To preview available tokens and corresponding column
names use the View Table Columns button which brings up helper information as shown below. The Preview
Query button allows you to see whether a query is working correctly.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 619
Chapter 9: Integrating with outside sources
If you are using an external database in a multi-tenant environment you need to ensure isolation of customers'
data. You can use the helper tokens {!#CURR_CUSTM.id} and {!#CURR_CUSTM.name} in WHERE clauses.
For instance, if you're using column CUST_ID to store customer's ID, add the following to the SELECT query:
.. WHERE CUST_ID={!#CURR_CUSTM.id}
Please use only tokens listed in the helper table. Other tokens will be ignored, making the SQL syntax invalid.
At runtime these tokens will be replaced with actual values from the records. This offers the most flexible way
to build queries which may include calls to stored procedures.
The following table explains the formats used by different types of data fields for tokens in external queries.
Field Type Format Example
String Text in single quotes. Single quite 'TEST' 'O''Neal'
inside text replaced by two.
Numeric Number 123.45
Date 'yyyy-mm-dd' '2012-06-15'
Date/Time 'yyyy-mm-dd hh:mm:ss.000' '2012-06-15 18:45:12.000'
Foreign Key Number or text in single quotes 123456 or 'XYZ'
Creating an external object from an external database table
If your tenant resides in a database marked as external, you can create object definitions that map to an existing
table in that database. Follow these steps to create an external object from an external database table:
1. On the application home page, click + in the application menu bar.
The What do you want to create? dialog opens.
2. Select A new Object (with Tab) from an External Metadata.
3. Click Next.
4. Select the table to use as the basis for your new external object. This can be any table other than the
following:
• A Rollbase table (name starts with RB_)
• A system table (name starts with ~)
• A table used by an existing external object
5. For the selected table, optionally select the text column to be used as the Record Name field.
If no column is selected, Rollbase creates the name from the Record Name Template or from the object's
single name if no template is provided.
620 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Using external tables as Rollbase objects
6. If desired, specify a single numeric unique column as the table's primary key.
7. Click Next.
8. If you have not specified a primary key, select one or more columns from the Available list and move them
to the Composite PK list with the right arrow. Reorder the Composite PK list as desired with the up and
down arrows.
9. Specify the usual object definition attributes:
• Singular Name
• Plural Name
• Integration Name
• Optional Description
10. Map columns in the selected table to new fields in the newly created external object. This is similar to
creation of fields while importing data from a CSV file, Excel, MS Access database, or Salesforce.com
object.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 621
Chapter 9: Integrating with outside sources
Each database column can be mapped to a field in newly created external object. These fields will be added
to the following pages: View, New record, and Edit. If you do not map column to a new field you can create
fields from unused columns later.
Importing data
Importing data is an easy way to add new records, update or delete existing records in bulk, or create new
objects and add records for them.You can import data from spreadsheets and comma-separated value (CSV)
files. For existing objects, the Import option is available from the page menu. You can also configure list views
to display an import link in the section header using the Page Editor. For creating new objects and associated
records, see Importing to create a new object on page 626.
Note the following before attempting an import:
• Spreadsheets must be saved in .xls format.
• The file to be imported cannot exceed 1MB. For Rollbase Private Cloud customers, the maximum file size
is configurable.
• Only data on the first worksheet of spreadsheet files will be imported.
• Rollbase assumes that each row starting from row 2 in a spreadsheet represents a record to be created or
updated. Row 1 is always interpreted as the header. When creating an object definition from a spreadsheet,
the header row provides the field names. The following shows a sample spreadsheet formatted for importing
into Rollbase:
• For picklist fields, Rollbase tries to find existing picklist values with the integration code or display name
that matches the value in the spreadsheet. If none exist and the Create new picklist items during import
check box is checked, Rollbase creates a new picklist value. However, as a precaution against potential
mismatches, Rollbase will not create new picklist values in picklists with a shared source (such as country
and state/province).
622 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Importing data
• For lookup fields where duplicate values are not allowed, such as those corresponding to the object name
or ID, the file to import from must have a column or field with unique values for each record. (To determine
which fields these are, navigate to the field definition in setup and view the field's Advanced Field Properties.
Do not allow duplicate values in this field will be checked.) When you map such a field during import,
the system will find any corresponding records with the matching record name or ID value and attach them
if found. To map more than one value to a lookup field, separate values with the pipe "|" character, such as
123456|789101. You can import complex data structures with Primary Keys (PK) and Foreign Keys (FK)
and replace the PK - FK with Rollbase relationships, see Importing related objects on page 627.
• Only one import job can be running in a customer tenant at a time; the current job must finish before anyone
can start a new job. Rollbase enforces this limitation for performance reasons.
• You can save the map you use to import with and manage the stored maps from the Data Maps section of
the object definition. In addition to a name, you can set an integration code for your map. Import maps can
also be used for data import through the REST API. For information on REST methods, see Rollbase REST
Methods on page 1201.
• Before importing a large amount of data, Progress recommends testing the process by selecting the Test
import mode that creates a detailed report for the first five rows in your spreadsheet. When you are satisfied
with the results, repeat the import with a larger amount of data.
• For large imports, Rollbase creates a job and places it into a queue for asynchronous processing and then
sends an email to you with results of the import once the job is completed. This message includes a report
detailing successfully imported records and errors encountered during the import process.
Note: To import data faster, Rollbase now enables the customers to set the thread count of the import job
scheduler that runs import jobs simultaneously. See System Console > System > Components >
Component Information .
• If a particular spreadsheet row contains errors such as an empty value for a required field, or unparsable
data, that row is ignored, but is reflected in the import report described next.
Import Report
For audit purposes, you can find import reports on the Administration Setup page, in the System Event Logs
section. The first line of an import report contains a timestamp indicating when the import process started. Due
to the queuing mechanism, there may be a delay between when you submit the import and when it actually
begins. Next, the results of each of the first five spreadsheet rows are displayed, by line number:
Started at 06/21/2015 06:16 PM
2: Import error: Field Permit No. cannot accept null values
3: Permit "Test 1" has been created
4: Permit "Test 2" has been created
5: Import error: Error importing data for mechanical_cost Field: For input string:
"1200-1300"
6: Import error: Error importing data for electrical_admin Field: multiple points>
Compatible import data types
When adding records to existing objects or when modifying records, the format of data in the spreadsheet must
be compatible with the data types of object fields. The following table describes the types of data expected for
Rollbase fields:
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 623
Chapter 9: Integrating with outside sources
Type Description
Numeric Single number
Check Box "true", "T", "y", "yes", "1" for true, false otherwise
Date Date in user's selected format or ISO 8601 format
Date/Time Date/Time in user's selected format or ISO 8601 format
Time Time in user's selected format
Duration Number of milliseconds for time interval
Lookup Name, ID, or selected unique field (see above) for
related record separated by '|'
Object Field Type Data Type to Import
Picklist (single), Radio Buttons Integration code or name of lookup item
Picklist (multiple), Group of Check Boxes Integration codes or names of lookup items separated
by commas or '|'
Workflow Status Integration code or ID of workflow status
Workflow Process Name or ID of workflow process
User's Role Integration code for role
Template Select ID of template
Date/Time Format Selector Number of selected format (from 0 - standard
US format)
Time Zone Selector Valid ID of time zone (such as
"America/Los_Angeles")
Parent Object ID of record to which communication log record
belongs
Importing for existing objects
Before importing, be sure to understand the requirements and how import works, as described in Importing
data on page 622.
To import a spreadsheet or CSV file to create new records, update existing records, or delete records, follow
these steps:
624 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Importing data
1. Navigate to the tab or view of the object you want to import.
2. From the page menu, select Import:
3. Click Choose File to select an Excel Spreadsheet (.XLS) or a comma separated value (CSV) file location.
4. If you selected a CSV file, specify its File Encoding format and CSV File Separator.
Note: By default, the file encoding is ISO-8859-1 and the file separator is a comma.
5. Choose the appropriate action for creating and/or updating records.
6. If you selected any action other than Create new records, select a Unique field from the drop-down list.
The value in this field will be used to ensure that the correct record is modified.
7. Click Next.
8. Map the fields of the destination object to columns in the uploaded spreadsheet by selecting the desired
spreadsheet column from the drop-down list on the right of each field. Rollbase makes a best guess at
automatically selecting field mappings based on the column headers in Row 1, but it is up to you to verify
and change mappings as needed.
• Not mapped prevents the field from being populated.
• Field default uses the default value set for new record creation. You must explicitly set this if you want
to use default values.
Read-only fields do not participate in mappings. Fields with the attribute This field is required in all forms
are highlighted in red and must be mapped to one of the spreadsheet columns to proceed.
9. Select the Import Mode:
• Normal — Runs all triggers on creation of new records and creates picklist values while importing rows.
This mode works best for medium-size imports.
• Test — Limits your import to the first five records and displays a detailed report. Use this mode to test
out your mapping before launching large imports.
• Bulk — Optimized for faster processing of large imports. In this mode, triggers are not executed and
new picklist values are not automatically created.
10. Optionally leave the Create new picklist items during import box checked if you want the system to create
new picklist items during import. This box is checked by default, and is not available in bulk mode.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 625
Chapter 9: Integrating with outside sources
11. Optionally click Save Map to use the same column to field mappings for other imports.
12. Click Submit to start the import process. Files less than 20KB in size will be processed immediately and
the results will display on-screen.
Importing to create a new object
Before importing, determine the singular and plural names for the new object and any object attributes you
wan to apply. For information on objects, see Object definition overview on page 77. Prepare a spreadsheet
you want to import in the Microsoft Excel (XLS or XLSX) or comma separated value (CSV) format.
To perform an import to create a new object, do the following:
1. Navigate to the application.
2. Click + in the application menu bar.
The What do you want to create? dialog opens.
3. Select A new Object (With Tab) from an External Metadata and click Create. The Import Object Metadata
page opens.
4. Click Spreadsheet File and click Next.
5. Do the following:
1. In the Spreadsheet File field, navigate to and select an Excel spreadsheet or a CSV file.
2. If you selected a CSV file, specify its File Encoding format and CSV File Separator.
Note: By default, the file encoding is ISO-8859-1 and the file separator is a comma.
3. Enter the Singular Name and Plural Name for the new object definition and optional object properties.
6. Optionally select the object attributes (see Object attributes on page 79)
7. Click Create Object.
8. For each spreadsheet column, select the appropriate action from the first drop-down menu:
• New Field — Create a new field and import a column's data into that field.
• Discard — Rollbase will not use the values in this column.
626 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Importing data
• Object_name — The lookup field. You must map one column to this menu item as shown in the example
below for a new Title object. Map a column that uniquely identifies each record.
9. From the Field Type column, select a data type for each field.
10. Optionally, change the default names for the new fields.
11. For fields that should contain unique values, check Do not allow duplicates.
12. Click Create Fields.
The data import proceeds. For small spreadsheets, you will see results on the screen. For larger imports,
you will receive an email.
Importing related objects
Importing from a spreadsheet limits you to importing one type of object at a time. It is often useful to be able
to set up relationships between imported objects. For example, you might have a database table of Vendors
with a primary key and a database table of Products with a foreign key pointing to the primary key of Vendors.
To import this data structure and preserve those relationships, follow these general steps:
1. Create a Vendor object definition.
2. Create a text field to hold the Vendor's primary key. Make sure to check the attribute Do not allow duplicate
values in this field.
3. Import Vendor data from a spreadsheet or CSV file and populate the fields, including values for each primary
key.
4. Create a Product object definition with a text field to hold the foreign key.
5. Create a many-to-one relationship between Products and a Vendor.
6. Import Products from a spreadsheet or CSV file. When importing, map the foreign key field to the unique
primary key field in the Vendor object.
If you no longer need the foreign and primary key fields, you can delete them. When you created the relationship
between the two objects, Rollbase automatically created fields to manage the relationship.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 627
Chapter 9: Integrating with outside sources
Deleting multiple records by importing a spreadsheet
To delete records, create a spreadsheet that lists unique field values (the field must not allow duplicates) for
the records you want to delete. The first row of the spreadsheet is interpreted as a header and should be the
name of the unique field. Use one spreadsheet for each object type. The process is similar to that used for
importing. Follow these steps to delete records using a spreadsheet:
1. From the application menu bar, click the object type for the records of interest.
• If the application uses the Traditional UI blueprint, click the object type for the records of interest from
the application menu bar. If you don't see the object of interest, check the overflow menu.
• If the application uses the Modern - Vertical Menus UI blueprint, click the object type for the records of
interest from the sidebar.
2. Select Import from the page menu.
The Upload Spreadsheet to Import page opens.
3. In the Spreadsheet File field, browse to and select the spreadsheet to import from.
4. Select the appropriate options for File Encoding and CSV file separator.
5. For Action, choose Delete existing records.
6. Select a Unique Field from the drop-down list.
The value in this field will be used to identify the records to be deleted.
7. Click Next
628 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Exporting from views and reports
8. Select the Import Mode:
• Normal: Runs all triggers on creation of new records and creates picklist values while importing rows.
This mode is best for medium-size imports.
• Test: Limits your import to the first five records and displays a detailed report. Use this mode to test out
your mapping before launching large imports.
• Bulk: Optimized for faster processing of large imports. In this mode triggers are not executed and new
picklist values are not automatically created.
9. Click Submit to start the deletion process. Small files (less than 20KB) are processed immediately and
Rollbase displays the results:
Exporting from views and reports
Rollbase provides export capabilities from views and reports. The header part of each view component contains
links to export the view's records in XLS, XLSX, CVS, or to a spreadsheet in Google Docs (see Integrating with
Google applications on page 630.). The following screen shows all the export formats available for a view in
Rollbase:
Exports created in this way are limited to 1000 rows for performance reasons.
You can hide individual export options by adding the following JavaScript code to Application custom header
section (to apply changes to the entire application).
<script>
rb.newui.options.listView.hideXlsExportOption = false;
rb.newui.options.listView.hideCsvExportOption = false;
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 629
Chapter 9: Integrating with outside sources
rb.newui.options.listView.hideGoogleExportOption = false;
rb.newui.options.listView.hidePDFExportOption = false;
</script>
By default all these export options are set to false. As per your requirement, you can modify these boolean
values to hide the export options from the menu.
If you want to hide all the export options, use Hide Export List View property from the Page Designer. These
options are available only in NewUI.
Integrating with Google applications
Rollbase provides an integration with Google applications as described in the following topics.
630 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Integrating with Google applications
In this section:
• Enabling Google integration on page 631
• Incoming Gmail on page 632
• Outgoing Gmail on page 634
• Google spreadsheets on page 634
• Synchronizing with Google Calendar on page 634
• Google Maps on page 635
Enabling Google integration
Before you can use Google integration from Rollbase, you need to:
• Provide your Google credentials.
• Enable IMAP on your Google account.
• If you are using Rollbase Private Cloud, see Enabling Google Apps for Rollbase Private Cloud on page 753
for instructions on updating required shared properties.
The following topics describe how to perform these tasks.
Providing your Google credentials to Rollbase
Google uses OAuth2 for authentication for its email, calendar, and spreadsheet functionality. Rollbase allows
you to attach to your Google account on the Third Party Settings page and stores the OAuth2 token in the
preferences framework. See My Third Party Settings on page 715 for instructions on providing your Google
credentials to Rollbase.
Enabling IMAP on your Google account
Rollbase access to your Google account information requires that your account uses IMAP. To enable IMAP
on your Google account:
1. Log in to your Google account and navigate to the Settings page.
2. Select the Forwarding and POP/IMAP tab.
3. In the IMAP Access area, select Enable IMAP (or verify that IMAP is already enabled):
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 631
Chapter 9: Integrating with outside sources
4. Click Save Changes.
IMAP is enabled for your account.
Incoming Gmail
Once you have provided your Google credentials and enabled IMAP on your Google account (see Enabling
Google integration on page 631), you can gain limited access to your incoming emails from within Rollbase.
Rollbase will read your Google inbox and display your messages. You have read-only access to your messages.
Messages are not stored in Rollbase.
You can access your email messages from the Email tab in the Rollbase application. You can also use the
page editor to add the Incoming Emails component to any generic page.
632 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Integrating with Google applications
The list of messages in your Gmail inbox displays the sender's email address, as well as the subject and date
of the email. Unread messages are shown in bold and starred messages have a star as you would see them
in your Gmail account. This list is sorted by date in descending order.
Click on a message's subject to view the entire message on the Message Details page:
Rollbase will try to match the email addresses in a message to the records in your tenant. If a match is found,
Rollbase display a link to the matched record as shown above.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 633
Chapter 9: Integrating with outside sources
If a message in your inbox was originated by Rollbase and relates to a particular record, Rollbase will resolve
this and display a link to that record as shown above.
From the Message Details page, you can:
• Select/deselect the star icon to flag/unflag the message.
• Click Communication Log to create a communication log record from this message and attach that record
to a selected Rollbase record.
• Click Delete to delete the email message (move it to the Trash folder in your Gmail account).
• Return to the message list.
Outgoing Gmail
To use your Gmail account from Rollbase, you must first provide your Gmail credentials and enable IMAP on
your Gmail account. See Enabling Google integration on page 631 for details.
By default, Rollbase uses its own email server when sending email messages from a Rollbase user. You can
change this behavior on the Third Party Settings page to specify that Rollbase should use Gmail (rather than
Rollbase email server) to send emails for this user.
If you specify that Rollbase should use Gmail for outgoing emails, Rollbase will use Gmail to send emails on
your behalf. This means that you will now see all Rollbase-generated emails in your Gmail account's Sent Mail
folder. In addition, when a recipient replies, Gmail will group reply messages with your original message for
convenience.
When you send an email using Gmail integration, Rollbase will display a reminder about it and give you a
chance to test your Gmail connections to ensure that your stored credentials are up-to-date with your Google
account.
Google spreadsheets
Once you have enabled Google integration for your Rollbase account (see Enabling Google integration on
page 631), you will have the option to export your views as spreadsheets in Google Sheets (in addition to Excel
spreadsheets, CVS files, and PDF documents). See Exporting from views and reports on page 629 for more
information.
To export a view to a Google Sheets spreadsheet, select Google when exporting a view. All of the data in your
view will be displayed as a new spreadsheet in Google Sheets. This gives you the convenience of Google
Sheets to work with and analyze your data, including the ability to share your data with other users who may
not have access to your Rollbase applications.
Synchronizing with Google Calendar
Events in the Rollbase calendar can be synchronized with Google Calendar. Events display in the Rollbase
calendar for object records that have the Event attribute.
634 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Integrating with Google applications
Synchronizing events with Google Calendar requires the following:
• Each user that wants to synchronize events with Google Calendar must enable Google integration and
enable Google Calendar synchronization. See Enabling Google integration on page 631 for details.
• Each object you want to synchronize with Google Calendar must have Google Calendar synchronization
enabled in the Event attribute of the object definition.
With synchronization enabled, when an event is created or updated in the Rollbase calendar, the creator’s
Google calendar will be automatically synchronized. Events marked as Private will also be private on the
Google calendar. You might need to refresh the Google calendar to view the result of the synchronization.
To enable Google Calendar synchronization, the object definition must have the Event attribute and the check
box must be selected for synchronization as shown below:
Google Maps
You can use Google Maps to visually represent a location associated with a record of an object with the
Location attribute. You do not need to enable Google integration with any account to use Google Maps.
You can add a Google map to an object's view page. To add a Google map to a view page, edit the page in
the page editor and drag the Google Map component to the desired location.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 635
Chapter 9: Integrating with outside sources
The Google Map component renders a map of the record's address as shown below:
You can configure a view page's Google Map component to select:
• The height of component in pixels. The map will take up 100% of the available width.
• The default zoom level. A user can change this at runtime.
• The default map type (street, satellite, etc.). A user can change this at runtime.
636 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Using SOAP or REST to integrate with Rollbase
To configure a view page's Google Map component:
1. Click Config next to the view page in the Pages area of the object definition:
2. Select the properties on the Configure Google Maps Component page:
3. Click Save.
Using SOAP or REST to integrate with Rollbase
The topics in this section discuss how to access Rollbase application data programmatically for integration and
extension purposes. When building integrations or external data manipulation tools that need to communicate
with Rollbase programmatically, you can use the Rollbase SOAP or REST APIs. The SOAP and REST APIs
expose the same functionality and use the same method names. A metadata API for both SOAP and REST
provides methods for creating and manipulating definitions of applications, objects, fields, and relationships.
The account under which metadata methods are invoked must have administrative privileges.
SOAP API
Rollbase uses literal WSDL encoding. If your SOAP infrastructure does not support literal WSDL encoding,
consider using the REST API. To make SOAP calls, the client must have a valid Rollbase user account with
login credentials. API users must have permission to view, create, update, or delete records to perform these
actions via SOAP API calls; the documentation for each SOAP API method specifies the required permissions.
Permissions cannot be set via the API; they can only be set by an administrator using the Rollbase user
interface.
The Rollbase SOAP API uses the same workflow mechanism as the standard Rollbase user interface. For
example, triggers designed to run on object record creation will run if a record is created through the SOAP
API. The Rollbase SOAP API uses the same permissions mechanism as the standard Rollbase user interface.
Changes in triggers, views, etc. might not immediately be updated on the Web services server. There might
be some latency due to caching.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 637
Chapter 9: Integrating with outside sources
To establish a SOAP API session, call the login() method, which takes user name and password credentials.
The login() call returns a session ID that must be used as the first parameter in all subsequent API calls.
To end a SOAP API session, call the logout() method.
See Rollbase SOAP Methods on page 1322 and SOAP Metadata Methods on page 1175 for descriptions of the
available SOAP methods.
REST API
REST calls require authentication and are subject to the same security procedures as normal user log ins. To
use this API requires a valid Rollbase user account with login credentials. The account must have permission
to view, create, update, or delete records to perform these actions using REST calls; the documentation for
each REST API specifies the required permissions. Permissions cannot be set via the API; they can only be
set by an administrator using the Rollbase user interface.
Supply user credentials in one of the following ways:
• Using a session ID — Call the login AP with valid credentials to receive a session ID. Supply that session
ID in every REST call as an HTTP header or URL parameter. At the end of session, call logout to end the
REST session. For example, this PHP code sets the HTTP header: header('sessionId:
'.$sessionId); This example passes the session ID in the URL:
&sessionId=1776eb2d56384f2d9d62f1bf83821b6d@5857
• By providing basic HTTP authentication through the HTTP header — Append @ and and the customer ID
to the login name. A PHP code example:
$header = base64_encode($userName.'@'.$custId.':'.$password); header('Authorization:
Basic '.$header);
Private cloud master tenant users can use their credentials to call the REST API on a specified tenant. REST
API calls using a session ID or basic authentication are considered to be made from behalf of the logged in
user. Permissions of that user are checked for each subsequent call. For instance, to update a record logged
in user must have EDIT permissions on that record, of API call will fail. Use of a session ID is preferred in terms
of performance and security.
Changes in triggers, views, etc. might not immediately affect the REST server. There might be some latency
due to the caching mechanism.
See Rollbase REST Methods on page 1201 and REST Metadata Methods on page 1188 for descriptions of the
available REST methods.
Limits on API calls
To protect Rollbase resources from overuse, the number of API calls is limited. The system calculates the
number of API calls (excluding login and logout calls) in 60-minute periods. If the number of calls during the
current period exceeds the maximum limit, no new calls are allowed until the current period ends and a new
counter starts.
The actual number of API hits allowed is determined by your subscription. You can find this information in the
Subscription Details page. Contact Progress Rollbase Support if you need to increase this limit for any reason.
Monitoring API calls
You can view information about API access to your tenant by navigating to Setup Home> Application Setup
> API. The API page provides the following information for monitoring:
• Runtime Info
638 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Integrating apps using Cloud Data Objects
• Maximum number of API calls per hour
• Number of REST API and SOAP API calls
• The time the API counter was reset
Note: The API counters are set at the time you log into Rollbase. For example, if you log into Rollbase
at 9:20 am, your API counters are set at 9:20 am and then the API counters are reset every 60 minutes.
• A link to API Logs.
This link opens the Monitoring setup page, which has links to API log files—SOAP API log, REST API
log, and Progress Data Service API log. The log files record every SOAP (webapi.log), REST (rest.log),
and Progress Data Service (progressdatacatalog.log) API call. You must select the Enable API Log
check box from Setup > Administration Setup> Account Settings to see detailed log records for API
calls.
• Server URL
• A URL for external applications to interact with Rollbase using a SOAP (WebAPI) call
• A URL for external applications to interact with Rollbase using a REST call
• A Progress Data Service URL for external applications to interact with Rollbase using
• A URL for external applications to interact with Progress Data Catalogs in Rollbase using a Progress
Data service call
• Development
• A link to the WSDL describing the elements in an object definition
• A link to the XML schema for an object definition
• A link to Progress Data Catalogs product page (Creating Progress Data Catalogs for external applications
on page 640)
• A link to the Code Generator that is used to generate code that can access Rollbase APIs from external
systems
• A link to Web API documentation
• A link to REST API documentation
• A link to Progress Data Catalogs documentation
Integrating apps using Cloud Data Objects
The Cloud Data Objects (CDOs) open source specification available from github provides a framework for
accessing Rollbase data. Progress provides an implementation of this specification, Progress Data Objects
(PDOs). Use of PDOs simplifies the integration of Rollbase application data into mobile and web apps. Rollbase
provides the server-side implementation, and you have a choice for creating client-side apps:
• A Rollbase Progress Data Service handles the REST calls. A Progress Data Catalog defines object structure
and the operations available to client apps.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 639
Chapter 9: Integrating with outside sources
Rollbase provides an All Objects data catalog, which contains all the objects in your tenant. You can create
additional catalogs with subsets of objects. For example, for simplicity and security a catalog should only
include the objects that the mobile app needs to access. Related objects must explicitly be included in the
catalog. You can view and manage catalogs from Setup Home or from individual application setup pages.
To include a catalog file when generating application XML to distribute the app, you need to create or attach
it from the application setup page.
• Client apps instantiate and access JavaScript Data Objects (JSDOs), which manage user sessions and
expose operations on Rollbase objects. You have the following choices for implementing mobile and web
client apps:
• The Progress Telerik Platform provides a template and built-in binding to UI elements which can further
accelerate mobile app development.
• Creating apps using HTML, JavaScript and CSS with your tool of choice and connecting to the Rollbase
back end using the JSDO. You can download the libraries containing the JDSO from
http://clouddataobject.github.io.
The information in this section describes how to create Progress Data Catalogs when using PDOs and JSDOs
with your tool of choice. To take advantage of PDOs with Telerik AppBuilder, see Using the Telerik Platform
to create a mobile app.
Creating Progress Data Catalogs for external applications
To create a new Progress Data Catalog, do the following:
1. Create the catalog from Setup Home or from the application setup page:
• Navigate to Setup Home. From the Applications Setup section, select Progress Data Catalogs. Or,
• Navigate to the application setup page Catalogs section.
2. Click New Progress Data Catalog.
The Progress Data Catalog screen opens.
3. Specify the following:
• Catalog Name: A unique name for the catalog.
• Integration Name: A unique integration name that Rollbase uses to identify this catalog in the customer
tenant.
Rollbase automatically assigns an Integration Name derived from the Catalog Name, but you are free
to change it.
• Description: Optional description of the catalog.
• Objects: In the Select Objects section, select and move the required objects from Available to Selected.
4. Click Save to save the catalog definition.
Rollbase creates the new catalog and displays it in the list of catalogs.
640 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Integrating with Microsoft Exchange Server
Integrating with Microsoft Exchange Server
Rollbase supports integration with Microsoft Exchange. This integration is supported in the following ways:
• At the user level, you can configure your third party settings to:
• Send emails from your Exchange account.
• View your Exchange emails in applications.
• The Email tab in the Rollbase application will list the email messages in your inbox.
• You can also add an Incoming Emails component to an application page and view your email
messages there. For example, you can create an Email tab for an application and place the Incoming
Emails component on a generic page associated with that tab.
• Synchronize your Rollbase calendar to your Exchange calendar (this is a one-way synch from Rollbase
to Exchange).
Use of Microsoft Exchange for your email and/or calendar must be enabled at the tenant level. It is enabled
by default. See My Third Party Settings on page 715 for instructions on configuring user-level Microsoft
Exchange settings.
• By default, Rollbase uses its own email server when sending administrative email messages from Rollbase.
You can configure a tenant to use an Exchange email account instead. See Email server settings for
instructions on configuring Rollbase to send administrative emails from an Exchange account.
• At the instance level, you can set shared properties to send administrative emails from an Exchange account.
Set the following shared properties to use Exchange for administrative emails at the instance level:
1. MailHost=Exchange
2. MailUser= [email protected]
3. MailPassword=myPassword
See Shared Properties on page 786 for more information.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 641
Chapter 9: Integrating with outside sources
642 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
10
Security and access control
The Hosted Rollbase infrastructure is hosted in a secure server environment that uses firewalls and other
security technology to prevent interference or access from outside intruders. The Rollbase Private Cloud
infrastructure is hosted in your own server environment that uses your own firewalls and security technology
to protect it. When you access the Rollbase service via HTTPS, Secure Socket Layer (SSL) technology protects
your information using both server authentication and data encryption, ensuring that your data is safe, secure
and available only to registered users in your account. As long as your authentication information (username
and password) are kept safe, your data remains inaccessible to unauthorized viewing and use. See User
authentication on page 644 for details about user authentication.
Rollbase provides a sophisticated set of access control mechanisms that allow you to grant users permission
to access applications and their components. See Access control on page 647 for details. Rollbase Private
Cloud provides additional access control mechanisms. See Private Cloud security and access control on page
837 for details.
Topics in this chapter describe security features that are available in both Hosted Rollbase and Rollbase Private
Cloud. See Private Cloud security and access control on page 837 for security features unique to Rollbase
Private Cloud.
For details, see the following topics:
• User authentication
• Access control
• User authentication and password management
• Enabling an administrative user to log into a customer tenant
• Enhanced hashing and encryption algorithms
• Security for portals
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 643
Chapter 10: Security and access control
• Enhanced Security and Authentication-related Features
User authentication
Users gain access to a Rollbase tenant when an administrator creates a User record for them. The record
includes a user name, which must be unique for the tenant, and an email address. Rollbase sends a welcome
email to that address. In case of public cloud, the mail contains a temporary password that the system generates.
This password must be changed during the first login. Neither the administrator nor Rollbase personnel have
access to user passwords. In case of private cloud, the email has an account activation link.
Note: The tenant level Turn off Welcome Email preference must be unset to receive welcome emails. See
Configuring Administrative Preferences on page 721 for more information. By Default, a user with No Access
role will not receive a welcome email.
If you do not want to send a welcome email immediately after creating a user, you can do so by adding the
Send Welcome Email checkbox to the create user page and unselecting it (by default, selected). After you
make the required user settings, you can edit a user record and select the Send Welcome Email checkbox
(by default, unselected) to send a welcome email.
Note:
• In a user record list view, the group actions menu offers options for sending welcome emails to selected
users. Even if selected, users with role as No Access will not receive a welcome email.
• Alternatively, you can send a welcome email to a user by selecting Send Welcome Email option from the
More Actions menu of a user record view page. The Send Welcome Email option will not be seen for a
user with role as No Access.
When a user logs in, Rollbase issues a session cookie to record encrypted authentication information for the
duration of a specific session. The session cookie does not include the user's password. Rollbase does not
use cookies to store other confidential user and session information, but instead implements more advanced
security methods based on dynamic data and encoded session IDs. Additionally, Rollbase implements HTTPOnly
cookies that direct browsers to expose the cookie only to HTTP and HTTPS requests.
A user can have only one Rollbase session open at a time. If a user logs in again in a different browser, Rollbase
terminates any previously opened Rollbase sessions (the only exception to this is API sessions).
Both Hosted Rollbase and Rollbase Private Cloud include the following authentication features:
• A user can reset a forgotten password.
• You can limit user logins to a configured set of IP addresses.
Rollbase Private Cloud allows you to configure the authentication method and several other aspects of user
authentication. For more information, see Private Cloud security and access control on page 837.
644 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
User authentication
Forgotten password
If a user forgets their password, they can click I forgot my Password on the login page. On the Forgot
Password page, the user should enter the email address for a valid Rollbase user account:
If the information matches Rollbase records, Rollbase resets the password and sends a new temporary password
to user's email address. The user will be asked to change the password at the first login.
Whitelist IP addresses
As a security precaution, you can restrict logins to a whitelist of IP addresses. The IP address of any user trying
to log in to your customer tenant will be checked against this list. If the IP address does not match, the login
will be denied.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 645
Chapter 10: Security and access control
To configure a whitelist of IP addresses:
1. Navigate to the Setup home page:
• From an application page, do one of the following:
• Select Setup Home from the Rollbase menu.
• Select Setup Home from the application switcher
• From a setup page, select Setup Home from the application switcher
2. From the Setup home page, select Whitelist under Administrative Setup. The Whitelist of IP Addresses
page opens.
3. In the Whitelist of IP Addresses area, specify IP addresses in one of the following ways:
• The exact address in x.x.x.x format
• A group of addresses (use * for the common part of the address)
• A host name to be resolved into an IP address
646 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Access control
You can apply the whitelist to a group of selected roles. If you want to apply the whitelist to all roles, do not
make any selection. To apply the whitelist to a group of selected roles, use the arrows to move roles between
the Available Roles and Selected Roles columns:
Access control
Rollbase provides a rich variety of mechanisms for access control that let you specify which users have
permission to access particular applications, objects, fields, and other components. These mechanisms include:
• Role-based access control, where you set permissions based on users' roles.
• User-based access control, where you set permissions for individual users.
• Relationship-based permissions on page 664, where you set permissions based on users' relationships to
objects.
• Location/Department/Function (LDF) permissions, where you allow access to particular objects and/or
relationships based on a hierarchical grouping of users.
You can choose to use the mechanisms that best meet the needs of your application and organization. The
detailed setting of all required permissions can be a tedious task, but it gives you full control over user access
to all data in Rollbase.
Rollbase checks permissions using the above mechanisms at the following times:
• When displaying applications and menus available to the current user.
• When displaying a list of records in a view or chart. If the user does not have access to certain records
(because of relationship-based permissions or LDF), they will not be shown.
• When displaying a page to view or edit a particular record. If the user is trying to access a record without
authorization, Rollbase displays an Access Denied error message:
• When presenting a list of records to create relationships (either in a p window or a picklist).
• When displaying search results.
• When accessing Rollbase through APIs.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 647
Chapter 10: Security and access control
When displaying links to related records, Rollbase does not check permissions for the current user. Permissions
are checked, however, if the user tries to navigate a related record.
The following topics describe how the mechanisms work and how to implement each.
Role-based access control
Role is a central concept in Rollbase security. Each user is assigned one role.
Rollbase provides four built-in system roles:
• Administrator: A user with full access to all objects and all customization features.
• Portal User: Assigned to authenticated users of external-facing portals.
• Portal Guest: Assigned to non-authenticated users of external-facing portals. Unlike portal users, portal
guests cannot log into a portal. Portal guests can only access public portal pages.
• Server API: Used to check permissions in server-side API calls.
You can define your own roles, add them to applications, and publish them along with other application
components such as objects. Publishing a role includes permissions assigned to that role.
The following topics describe how role-based access control works, how to create roles and assign users to
them, and how to set permissions for roles.
Roles and permissions
A user has all permissions assigned to that user's assigned role. In addition, you can assign individual
permissions to a particular user. See User-based access control on page 662 for more information.
You can assign the following permissions by role:
• Permissions to access selected applications.
• If a particular role has access to an application, that role will be given default access to newly created
components of that application unless you override this access.
• If a particular role does not have access to at least one application, and at least one tab in that application,
a user with that role will not be able to log in to Rollbase.
• Permission to access object records, including view, create, edit and delete permissions per object type.
• Permission to view object fields in the user interface, and the ability to specify that a field is read-only in the
user interface for particular roles. For API access, permissions for fields are determined by permissions for
the object type.
• Permission to access views, tabs, charts, reports, and workflow actions.
• Permission to access menus, including submenus.
• Administrative permissions that can be granted to any user-defined role (but not non-administrative system
roles):
Permission Granted by default
Manage (create, modify and delete) views No
Manage (create, modify and delete) charts No
648 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Access control
Permission Granted by default
Manage (create, modify and delete) reports No
Manage currency exchange rates No
Send individual and mass emails Yes
Use Print, PDF, and Spreadsheet export links Yes
Convert records to different object type Yes
Merge multiple records into a single record Yes
Manage (create, modify and delete) import maps Yes
Manage Roles No
Manage Security Settings (authentication and No
whitelist)
Manage Monitoring (monitor setup, system jobs, user No
sessions, portal visitors, system logs, and support
access sessions )
Manage Currency Codes No
Manage Email Server Settings No
Manage Customer Preferences (preferences and No
localization settings)
Manage Backups No
Manage Global Text Search No
Manage Users No
Configure Support Access No
View Integration Password Yes
Note the following about the above administrative permissions:
• Merge and convert functionality also require permission to create a new record of the selected object
type. Objects include system entities that can be used in reports, such as activity trails, comments, and
login history records.
• When a role is granted the Manage Roles permission, users with that role can create and edit roles.
They can only create roles with the same set of permissions as their own role or with a subset of those
permissions. They cannot manage the Administrator role or their own role. They cannot assign any
administrative permissions to any role.
• When a role is granted the Manage Users permission, users with that role can edit users if they have
the appropriate permissions on the User object. They cannot assign the Administrator role to a user.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 649
Chapter 10: Security and access control
• When a non-administrative role is granted the View Integration Password permission, they can view the
password field values in plain-text for REST, SOAP, and AJAX calls. If no permission is granted, the
password field value is returned as Password on File.
This permission can’t be granted to non-administrative system roles – Portal User and Portal Guest.
This permission does not apply to Server Side APIs or field tokens used in template/trigger body. They
always return password as plain-text value.
• When a non-administrative role is granted the Search Box permission, they can view the search button.
If no permission is granted, the search button is not enabled for users with that role.
This permission can’t be granted to non-administrative system roles – Portal User and Portal Guest.
Creating and editing user roles
User roles determine the permissions for the group of users who are assigned to that role. You can create a
new role directly or based on multiple existing roles. When a new role is created based on existing roles, it
offers the benefit of performing multiple functions, as it inherits pages and a union of permissions of the selected
roles and acts as a super-set of those roles.
Perform the below steps to create a role.
1. Navigate to the Setup home page:
• From an application page, do one of the following:
• Select Setup Home from the Rollbase menu.
• Select Setup Home from the application switcher
• From a setup page, select Setup Home from the application switcher
2. In the Administration Setup section, click Roles.
The Roles grid appears with the list of currently defined roles:
3. To create a New Role, perform the following steps. Alternatively, to create a role based on the existing
roles, jump to Step 4 of this topic.
a) Click New Role from the Roles grid. The New Role creation page appears.
b) In the Define User Role section, type the Role Name.
c) Type the Integration Code to use this role in formulae and triggers. This is optional.
d) Type a Description of the new role.
650 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Access control
e) In the Select Applications section, select application(s) from the Available Applications select box
and move those to the Selected Applications.
f) Save to view the newly created role in the Roles grid.
4. Creating a new role from existing roles.
a) In the Roles grid, click New Role from existing....
b) In the Define User Role section, type the Role Name, Integration Code and provide a Description of
the new role.
c) From the Choose Roles to Inherit Permissions section, select roles from the Available Roles and
move those to the Selected Roles list. A new role is created, which inherits permissions based on the
selected roles. You may choose to fine-tune the permissions once the role is created.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 651
Chapter 10: Security and access control
• Note that you must select a minimum of two existing roles to create a new role. Alternatively, you
may select a maximum of ten roles.
d) The list of selected roles will appear in the Select Role drop-down of the Choose a Role to Assign
Page Versions section.
e) Select Role from the Choose a Role to Assign Page Versions section, to map default pages of the
selected role to the newly created role.
The new role inherits page assignment settings based on the selected role. You may choose to configure
the pages once the role is created.
f) Save. The newly created role appears in the Roles grid.
NOTE:
• Authentication profile will default to the current system default
• Permissions for the new role will be a union of all the roles selected
• The new role is independent of the existing roles. This means that the user assignment is not inherited
and needs to be done separately. The new role does not replace any existing role.
• Role landing page property is not inherited.
5. Upon successful creation of a role, click Edit to configure its properties. The available fields for edit are
Role Name, Integration Code and Description.
6. Click Clone to copy an existing role and save as it a new role.
7. To configure Permissions, see Setting permissions by role on page 654 for more information.
8. To assign a landing page for the role and configure the Pages, see Assigning a landing page to a role on
page 656 for more information.
9. To view a role, click the role name.
652 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Access control
Assigning a role to a user
Each user has one role. You can assign a role to a user when creating a User record and you can edit an
existing User record to change the role.
To assign a user's role:
1. Navigate to the Setup home page:
• From an application page, do one of the following:
• Select Setup Home from the Rollbase menu.
• Select Setup Home from the application switcher
• From a setup page, select Setup Home from the application switcher
2. Click Users under Administrative Setup.
3. Click Edit next to the user you want to edit.
The user edit page opens.
4. In the Login and Role area, from the User Role drop-down field, select a role. You can also select No
Access, in which case the user cannot access any applications or components.
Note: By Default, a user with No Access role will not receive a welcome email.
5. Click Save. The user now has the selected role.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 653
Chapter 10: Security and access control
Setting permissions by role
The Permissions page for a role allows you to set the following permissions for that role:
• Administrative permissions
• Application permissions
• Object permissions, including an object's related views, reports, charts, and workflow actions
• Tab permissions, including a tab's menus
The ability to manage all permissions for a particular role makes it easier to manage that role's permissions.
You can filter the view by application to see only the objects and tabs for a single application.
To set these permissions by role:
1. Navigate to the Setup home page:
• From an application page, do one of the following:
• Select Setup Home from the Rollbase menu.
• Select Setup Home from the application switcher
• From a setup page, select Setup Home from the application switcher
2. Under Administrative Setup, click Roles.
3. Click Permissions next to the role whose permissions you want to edit.
The Permissions page opens and displays all permissions for that role, including:
Administrative permissions:
Application permissions:
654 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Access control
Object permissions and permissions for each object's views, reports, charts, and workflow actions:
Tab permissions and permissions for each tab's menus:
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 655
Chapter 10: Security and access control
4. Optionally select an application from the Filter By Application drop-down field to filter the view by application.
The page will now display only permissions for that application and its objects and tabs, as well as
administrative permissions for the role.
5. Set the permissions as desired.
When setting permission for objects:
• You can specify a combination of View, Create, Edit, and Delete permissions
• You can click Select All to grant all permissions for the object and its views, reports, charts, and workflow
actions.
• You can click Select none to clear all permissions for the object and its views, reports, charts, and
workflow actions.
• You can also grant or clear permissions individually.
When setting permissions for tabs:
• You can click Select All to grant all permissions for the tab and its menus.
• You can click Select none to clear all permissions for the tab and its menus.
• You can also grant or clear permissions individually.
6. Click Save.
Users with that role now have the selected permissions.
Assigning a landing page to a role
You can assign a landing page to a role. The configured landing page includes the application page and the
tab to open on that page. When a user with that role logs into Rollbase, the configured page opens with the
configured tab selected.
To assign a landing page to a role:
1. Navigate to the Setup home page:
656 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Access control
• From an application page, do one of the following:
• Select Setup Home from the Rollbase menu.
• Select Setup Home from the application switcher
• From a setup page, select Setup Home from the application switcher
2. Select Roles.
3. Select Pages next to the role to which you want to assign a landing page.
The Assign Page Versions page opens.
4. Select the Configure landing page for the role check box.
5. From the Select Application drop-down list, select an application.
6. From the Select Tab drop-down list, select a tab.
7. Click Save.
When a user with that role logs in, the configured application will open with the configured tab selected.
A user can override the landing page configured for their role on the My Preferences on page 716.
Setting component-level permissions
You can set component-level permissions on an object, tab, menu, view, report, chart, or workflow action.
The setup pages to view and edit these components include a Permissions section where you can click Edit
Permissions to set permissions for different roles.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 657
Chapter 10: Security and access control
You can also set these permissions on a role's Permissions page as described in Setting permissions by role
on page 654. Setting permissions on a role's Permissions page allows you to see all views, reports, charts,
and workflow actions associated with a particular object and all menus associated with a particular tab. This
makes it easier to set a group of related permissions.
On an object definition, you can set View, Create, Edit and Delete permissions. Users in a particular role will
have the specified permissions for object records of that type:
On a view or a chart, you can set a single View permission. A user's role (or the user) must have View permission
on the associated object to be able to access the view or chart.
Note: Limiting access to views can be useful for limiting user access to certain kinds of records, provided that
the user is not permitted to create or edit views. However, we do not recommend this approach. Using
relationship-based permissions or location, department, and function (LDF) based permissions is more secure
and reliable.
On a tab, menu, report, or workflow action component, you can set a single Access permission. A user's role
(or the user) must have the appropriate permission(s) on the associated object(s) to be able to access a report
or a workflow action.
658 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Access control
Setting field-level permissions
You can set view and edit permissions on fields for any role. For both view and edit permissions, there are
three options:
• Yes — Users with that role are granted that permission.
• No — Users with that role are not granted permission.
• Conditional Formula — Users with that role are only granted permission if the associated conditional
formula returns true.
You can only grant edit permission to a role if that role has view permission.
To set field-level permissions:
1. Navigate to the object definition page.
2. Select Fields from the ribbon.
3. Click Permissions next to the field for which you want to set permissions:
4. Select each role's View and Edit permissions, specifying Yes, No, or Conditional Formula as shown
below:
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 659
Chapter 10: Security and access control
5. If you selected Conditional Formula for a position, click Formula to edit the formula.
The following screen shows a conditional formula. In this example, the createdBy field (whose value is a
user link), must equal the current user to grant edit permission on the Comments field.
Note the following when implementing field-level permissions:
• For performance reasons, keep conditional formulas short.
• To grant edit permission on a field, you must also grant view permission on that field. This applies to both
non-conditional and conditional permissions.
• Edit permission is granted for any activity that creates or updates records, including Edit pages, New pages,
Quick Create pages, Mass Update pages, and inline editing.
• For mass updates, Rollbase updates only those records for which the condition formula returns true.
• If a field is required (Always require a value in this field in order to save a record is checked for the
field), and edit permission is not allowed on that field for a user's role, the field permission takes precedence.
Rollbase does not validate the field and the user can save the record with no value for that field.
• Permissions to access fields from APIs are determined by permissions on the fields' object types, not by
field-level permissions.
660 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Access control
• When you use conditional permission, note the following behavior: If the view conditional formula returns
true and the edit conditional formula returns false for a field on a page, the page displays the field but
does not allow the user to enter a value in the field. If the view conditional formula returns false, the field
does not appear on the page.
• When writing a formula for conditional edit permission, note that the current record context is not available
during record creation. To write a formula that covers both create and update cases, either conditionalize
the formula to execute different code for create and edit scenarios or use tokens such as Current User,
Current Customer, Settings, and Helpers, which are always available.
You can conditionalize formulas to execute different code for record creation and record update by checking
the current record id, {!id}. If it has a non-zero value, the formula is executing on an existing record and
the current record context is available. If it evaluates to zero, the record is not yet created and the formula
is executing for a new record.
The following example illustrates a pattern for conditionalizing a formula to execute different code for record
creation and record update.
var recordId = {!id};
if(recordId > 0) {
// Update Scenario
if(!rbv_api.isFieldEmpty("Passenger1", recordId, "R7428"))
return true;
}
else {
// New Record scenario
return true;
}
The following example illustrates using tokens based on the Settings record, which is always available.
if("{!#SETTINGS.club_member#value}" != "")
{
return true;
}
You can also set field permissions using the setPermissionsByRole REST method.
Setting user permissions for roles
You can set User Permissions for roles. While they appear on the user Permissions screen, you can only
edit them for a role.
These permissions are all enabled by default for every role. Administrators can disable/enable each of these
permissions for a role.
User Permissions include:
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 661
Chapter 10: Security and access control
• My Settings — When disabled, users with that role cannot manage the settings on their My Settings
screen. My Settings will not appear on the My Profile screen.
• My Third Party Settings — When disabled, users with that role cannot manage the settings on their My
Third Party Settings screen. My Third Party Settings will not appear on the My Profile screen.
• My Localization Settings — When disabled, users with that role cannot manage the settings on their My
Localization Settings screen. My Localization Settings will not appear on the My Profile screen.
• Recycle Bin — When disabled, users with that role cannot manage their recycle bin. Recycle Bin will not
appear in the Rollbase menu or on the My Profile screen.
• My Security Settings — When disabled, users with that role cannot manage the settings on their My
Security Settings screen. My Security Settings will not appear on the My Profile screen.
• My Theme — When disabled, users with that role cannot set the theme on the My Preferences screen.
The My Theme area will not appear on the My Preferences screen.
• Notifications — When disabled, users with that role cannot edit Notifications on the My Preferences
screen. The Notifications area will not appear on the My Preferences screen.
• Landing Page Configuration — When disabled, users with that role cannot set the Landing Page
Configuration on the My Preferences screen. The Landing Page Configuration area will not appear on
the My Preferences screen.
If My Theme, Notifications, and Landing Page Configuration are all disabled for a role, My Preferences will
not appear on the My Profile page for users with that role.
The following screen shows the My Profile screen for a user whose role does not have permission for Recycle
Bin, My Theme, Notifications, and Landing Page Configuration:
User-based access control
You can set permissions for individual users on applications, components, and fields the same way you can
set permissions for roles. If either a user or that user's role has permission to access something, that permission
is granted to that user. For server-side APIs, Rollbase also uses the Server API role to grant permissions. See
Server-side API on page 949 for more information.
662 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Access control
You set a user's permission the same way that you set permissions for a role:
• To view and set all permissions for a user, select Users from the Administrative Setup area of the Setup
Home page. A user's Permissions page is similar to a role's Permissions page. See Setting permissions
by role on page 654 for more information.
• To set component-level permission for a user, in the Permissions table on the component's view page,
click Select User, select the user from the list, and set the permissions.
In the example below, the user Joe Recruiter is granted permission to view object records, even though that
user's role, Officer, does not have that permission:
There are also access control features that apply only to users:
• The Private attribute on events, tasks, reports, and templates
• The Record Creator role
The following topics describe these features.
The Private attribute
Events, tasks, reports, and templates provide a Private attribute that introduces additional visibility limitations:
• Private reports are only visible to their creator and to administrative users.
• Private email and document templates are only visible to their creator and to administrative users.
• Private events and tasks are only visible to their creator, users with which they have direct relationships,
and administrative users.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 663
Chapter 10: Security and access control
The Record Creator role
Record Creator is a system role Rollbase assigns when a new record is created. This role allows you to set
permissions by object type for users who create records. Because the Record Creator role only applies to
object records, it only appears when you are creating and editing object definitions. You set Record Creator
permissions in the Permissions section when editing an object. The Record Creator role only applies to a
user who creates a specific record of that object type; for all other access, the user retains its normal role.
Consider the following example: Users of your Customer Service application (for this example, user accounts
with the Service Customer role) can create Support Request records, as well as browse and manage a list
of their own requests. To achieve this access, set the following permissions on the Support Request object:
• Service Customer role: Create only
• Record Creator role: View, Edit, and Delete
Users with the Service Customer role can create Support Request records, but cannot view, edit, or delete
Support Request records. However, once they create a record, they have permission to view, edit, and delete
it through the permissions granted to the Record Creator role. This ensures that Service Customers can view
and edit only their own support cases.
Relationship-based permissions
You can use a relationship between a user or a portal user and records to give that user access to related
records only, rather than to all records of that type.
You can assign permissions through relationships when editing object-related permissions or you can navigate
from the Permissions link in the Relationships section:
Consider the following example: You want to limit the access of users in the Account Manager role to Order
records, only allowing users in that role to view, edit, and delete records that they own while allowing any user
in that role to create records. There is a one-to-many relationship between User (the relationship is named
Owner) and Order. To achieve this, specify the following permissions:
• On the Account Manager role: Create
• On the Owner relationship: View, Edit and Delete
664 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Access control
For dependent records, such as Order Line Items in the example above, use role-based permissions. This
strategy works because the user can only access these dependent records through the parent record, access
to which is controlled through the relationship.
User hierarchy of permissions
Permissions through relationships are only granted to the users with a direct relationship to the record. However,
in many business cases, users are in hierarchical relationships, such as manager-subordinate. In these situations
it is unusual to give access to lower levels of the hierarchy without providing access to users higher up in the
reporting structure.
To solve this issue, Rollbase provides a "hierarchy of users" relationship: Direct Reports (one-to-many) and
Reports To (many-to-one). For example, the Reporting Structure shows the list of Direct Reports who report
to the user Mike Sancilardi and the Reports To field shows the list of people to whom Mike Sancilardi reports
to.
Rollbase calculates a sub-tree of users who report (directly or indirectly) to the current user. All relationship-based
permissions given to that sub-tree are also delegated to the current user.
Consider the following user hierarchy:
• Joe Recruiter
• Mike Sancilardi (reports to Joe)
• Taras Bulba (reports to Mike)
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 665
Chapter 10: Security and access control
None of the users' groups have permission to access Order records, but the Owner relationship has full access:
There are three orders in the system with different owners. An administrator sees all three orders:
Joe Recruiter sees two orders (even if he does not own them directly). Access to these orders is granted
through ownership of direct and indirect users below him in the hierarchy:
666 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Access control
Page versions
When you create an object definition, Rollbase creates a complete set of pages for viewing, editing, and creating
records for that object. You can create different versions of these pages using the Clone link in the Pages
table. Use the Page Editor to modify these cloned pages.
Later, you can assign these cloned pages to be used by individual users or those with particular roles. Use the
Pages link in the Roles list or select Assign Pages from the drop-down menu on the user view page to assign
pages by role and user:
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 667
Chapter 10: Security and access control
668 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Access control
On the Assign Page Versions page, expand the object for which you want to assign pages and select the
pages you want to assign for the role or user. Different users or roles can use different pages to access the
same records. This approach can be used to limit a user's access to certain object fields and/or to personalize
a the experience by user and role.
Location/department/function permissions
Location/Department/Function (LDF) permissions are the most complex types of permissions to set up in
Rollbase. Typically, large organizations with complex internal policies require the level of access control provided
by LDF.
LDF permissions act as filters that are applied before any role-based, user-based, or relationship-based
permissions are applied. LDF permissions are set on individual records. This is in contrast to user, role, and
relationship-based permissions, which are set on objects and components such as views. LDF permissions
specify whether a user can access a particular record. Actions on records, such as viewing, editing, creating,
and deleting, are controlled by user, role, and relationship-based permissions.
The system User object has LDF permissions enabled by default. LDF permissions are enabled by adding the
Organization attribute to the object. If an administrator has disabled LDF permissions for the User object, you
can re-enable them by adding the Organization attribute to the User object.
LDF permissions are based on the following objects defined in the Organization Management standard
application, which you must install before you can use LDF permissions::
• Location
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 669
Chapter 10: Security and access control
• Department
• Function
• Group
When you set up LDF permissions, you use Location, Department, and Function to model an organization.
Each of these objects allows you to create records in a hierarchical structure, such as shown in the screen
below of Department records where Telesales and Regional Sales fall under the Sales category:
The Group object represents a group of users. Each Group record can have a Location, a Department, and
a Function, as well as a list of users who are members of the group. A user can belong to zero or more groups.
LDF permissions apply to a group. A user will have the superset of the LDF permissions specified for all of the
group(s) to which the user belongs. See LDF groups on page 673 for more information about groups.
You set LDF permissions on records. LDF permissions are enabled for an object by adding the Organization
attribute to it, which adds the Location, Department, and Function fields to the object. You then assign values
to these fields in records. Users who belong to a group whose values are the same or higher in the hierarchy
than the values in an object record can access that record. See Assigning LDF values to records on page 677
for details about setting LDF values in records.
670 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Access control
The example below illustrates how LDF permissions work; normal permissions are applied after LDF permissions.
In this example, Joe has permission to access the Acme Lead record because the group Sales Reps has
permission to access records with the location Boston and the department Sales. However, user/role/relationship
permissions still apply. For example, for Joe to view the record, Joe must also have View permission for the
Lead object.
The example below shows how LDF permissions work with hierarchical values. The function Sales Rep is a
child of the function Sales VP. Joe can access the Acme Lead record because his group's function is Sales
VP and the Acme Lead record's function is Sales Rep. However, the Lead object must allow View permission
for either Joe or for the Sales Mgmt role for Joe to view the record.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 671
Chapter 10: Security and access control
The example below show how LDF permissions can prevent a user from accessing records outside of that
user's organization. In this example, Joe's group has the location Boston, but the Acme Lead record has the
location Chicago. Therefore, Joe cannot access the record, even if the user Joe or the role Sales Mgmt is
granted user-based or role-based permission to access it.
You can set up LDF permissions in any way that matches your organization's needs.
Note: Adding LDF permissions to large number of records can affect application performance. Progress does
not recommend adding LDF permissions to dependent objects (such as order line items) which are accessible
only through a master object (order).
Follow these general steps to implement LDF permissions:
1. Install the Organization Management application. See Installing and updating applications from the
Marketplace App on page 125 for information about installing applications.
2. Create records in the Location, Department and Function hierarchies as required.
3. Define groups for your users and assign LDF attributes to each group.
4. Enable the Organization attribute on objects for which you want to user LDF permissions.
5. Assign LDF values to object records.
The following topics describe how to set up LDF permissions.
672 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Access control
LDF hierarchies
The Organization Management application includes Location, Department, and Function objects, and is
pre-populated with a set of base records. Each set of records is organized in a hierarchy. For example, a portion
of the location hierarchy is pre-populated with the following:
You can add, edit, and delete records in the hierarchy according to your requirements. For LDF permissions,
if a group has permission to access a location, department, or function, it also has permission to access its
children. For example, in the above graphic, if a group has permission to access records with the location
United States, it also has permission to access records with the locations Chicago, IL, Houston, TX, and the
rest of the child locations.
LDF groups
The Organization Management application contains a Group object that allows you to assign combinations
of LDF values to groups and to add users to groups to create sophisticated organization-based permission
structures. Each group has zero to three assigned LDF values. This means members of that group have
permission to access to all LDF records (regardless of their object type) that match these values (root node or
any node below it).
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 673
Chapter 10: Security and access control
When you create a group, you give it a name and assign values to any or all of the LDF fields:
674 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Access control
You can assign individual users to a group in one of two ways:
• Edit a user and assign it to one or more groups. To do this, you first need to edit the Edit User page to add
the lookup field Groups to the page (see Editing pages on page 369 for details). The resulting selector on
the page opens a window and allows you to select one or more groups:
• Edit a group and add users to it. To do this, you first need to edit the Edit Group page to add the lookup
field Users to the page (see Editing pages on page 369 for details). The resulting selector on the page opens
a window and allows you to select one or more users.
The screen below shows the view page for a user who is a member of two groups. The read-only LDF Filter
field shows the exact LDF permissions for the user. The LDF Filter field is useful for verifying a user's assigned
permissions. The Groups field displays the user's group memberships. Within each group, attributes are
connected by a logical AND. Groups are connected by a logical OR. In this example, Mike has permission to
access all locations under United States for the department Operations because the Executives group is
assigned the location United States:
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 675
Chapter 10: Security and access control
Keep the following in mind when creating groups and assigning users to them:
• If a record has no value for an LDF field, only users whose group has no value for that field can access the
record. For example, if a record has no value for the Department field, a user whose group has the value
Sales for Department cannot access that record.
• If you create a group without any LDF values, members of that group will have full access to all records
with LDF permissions enabled. Only users in that group or an administrator can access a record with no
assigned LDF values.
• A non-administrative user that does not belong to any group does not have access to any records with LDF
permissions enabled.
• Administrative users have full access to all records.
Enabling the Organization attribute
To use LDF permissions on object records, you must enable the Organization attribute on the object type. To
enable this attribute:
1. From the application switcher drop-down available next to the application name:
• To navigate to settings for the current application, click App Settings.
• To navigate to settings for a different application, hover your mouse pointer over the application and
click its associated Application Settings icon.
2. Click Objects in the ribbon.
3. Click Edit next to the object to modify.
676 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Access control
4. In the Object Attributes table, check Organization.
5. Click Save.
You can now assign LDF permissions on individual records of that type.
Assigning LDF values to records
LDF permissions are set on individual records. This is in contrast to user, role, and relationship-based
permissions, which are set on objects and components such as views.
When you add the Organization attribute to an object, the Location, Department, and Function fields are
added to its view, edit, and new pages. When you create or edit a record, you can select values for these fields.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 677
Chapter 10: Security and access control
When you view a record, the values for these fields are displayed and, in addition, the LDF Filter field displays
the rules for accessing the record. The LDF Filter field is useful for verifying the assigned permissions for an
object record:
678 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Access control
Assigning LDF values for all records can be a tedious task. To simplify it, you can use the following techniques
to assign default LDF values to new records:
• The User object always has the Organization attribute (unless it has been disabled by an administrator),
so you can assign LDF values directly to users. This does not grant any LDF permissions, as permissions
are always granted through groups. Instead, these values can be used as the default when a particular user
creates LDF records. To use default LDF values assigned to the current user, check the option on the Edit
Field page for that object. For example, in the graphic below, the Location field for the Order object has
this option checked. When a user creates an order record and does not provide a location, the user's location
is used as the default.
• If you create a new related record, and LDF fields are absent from the new record page, the LDF values
from the parent record are used by default. You must create the new related record from the parent record's
view page; for example, in the screen below, you would click New Order Line to create a related order line
with the order's LDF values:
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 679
Chapter 10: Security and access control
User authentication and password management
Introduction
User management requires policies and techniques for new users and revised user credentials:
• Knowledge Factor Token for User Authentication - Adds an additional security check for users.
• User Initiated Password Reset - Sends a notification email after a user has updated their password.
• Changing the Password Reset Link - Changes the password reset link, and does not send a temporary
password.
Knowledge Factor Token for User Authentication
On the authentication page for passwords, an administrator can choose additional security for users. When
the Use Knowledge Factor Token option is selected, a drop down list of fields are enabled. The admin can
decide which field to use for user validation at first login and after password reset.
680 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
User authentication and password management
The knowledge factor token is an authentication credential consisting of information that a user possesses,
such as a personal identification number (PIN), user name, password, or answer to a secret question. When
the user accesses their login link, they have to provide that value. Once authenticated, the user can set their
preferred password.
User Initiated Password Reset
Typically, a user can change their password:
• When logged in, by accessing the user profile, and then clicking Change my Password.
• Before logging in, by clicking on the forgot password link. This link takes the user to a reset page where the
user provides validation and then creates a new password.
In either case, an email is sent to the user to notify them that their password was successfully changed.
Changing the Password Reset Link
Rollbase generates a unique link everytime a new user account is activated or a user tries to reset the password.
The one-time activation link generated is user specific and if it is valid and in the time window, the user can
enter their login name, and then click Submit.
When accepted, the user sees the Change Password page where the user enters a new password, and
answers configured security questions. The user is then sent an email to inform that their password was
changed.
The user can request for the password reset link multiple times. Once the password reset link expires, the user
can perform the Forgot Password action again or request the administrator to reset their password. The default
expiry time for the new user activation link or password reset link is 2 hours. This can be configured by modifying
the shared property, NewUserPasswordActivationLinkExpiry (for new user activation) or
PasswordActivationLinkExpiry (for password reset), at system level or authentication configuration at a
tenant level by specifying the duration in the Password Activation Expiry Time field under Administration
> Setup Home > Administration Setup > Authentication > Password .
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 681
Chapter 10: Security and access control
Note:
Password reset link email expiration time and New user creation activation link expiration time are now separate
operations and the links sent via email will persist across Rollbase restarts as well.
In case of Rollbase upgrade, the value configured for Password Reset Expiry Time is applicable only for
Password reset Expiry Time field but not for the New User Activation Expiry Time.
The New User Activation Expiry Time field value needs to be explicitly changed after the upgrade.
The reset password link expires in the following cases:
• If the activation link is not used within the specified time frame, the activation link expires
• In case of multiple reset password requests, once a new password reset request is raised, the existing reset
password link expires
• Once the activation link is used within the time frame to reset the password, the link expires
.
Note: The password reset link expiry time and the knowledge factor token can be retrieved and/or set using
the getAuthentication and setAuthentication REST API methods . See getAuthentication on page 1218 and
setAuthentication on page 1256methods for more information.
Error logging
Rollbase provides error logs when an invalid user name is entered or the password link expires. The tenant
administrator will be able to see these error logs in Setup Home>Monitoring>System Error Log. Below listed
are reasons that can produce errors.
Error Message Reason
Invalid User Name or Password. Please try again. If A user enters a login name that is not present in the
you have forgotten your password, please use "Forgot system.
password" link to reset it.
Invalid User Name entered by the user for activation A user enters a login name present in the system but
not associated with the given activation url.
Password activation link has expired for user The activation url has expired for a user. The activation
url time is set using the
PasswordActivationLinkExpiry shared property.
See Shared Properties on page 786 for more
information.
Note: If you do not see the error message printed at
Setup Home>Monitoring>System Error Log, check
login.log.
Deprecated Tokens
682 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Enabling an administrative user to log into a customer tenant
The following tokens are deprecated when resetting the password and will not be shown in the Password Reset
Notification Template. You can remove these tokens, otherwise, Rollbase will ignore these tokens.
{!#user_name_#}
{!loginName}
{!#temporary_password_#}
{!tempPassword}
{!#after_you_login_usin#}
Enabling an administrative user to log into a customer
tenant
The administrator of a customer tenant can allow master tenant users to access its environment for a specified
duration. Typically, if a customer tenant requires that the master users troubleshoot a problem in its account,
the customer tenant gives access to the master users for them to rectify the problem. After getting the access,
the master user can access the customer details page and log into the customer tenant. For more information
about how master users log into a customer tenant, see Working with customer records on page 825.
To enable a master tenant to log into a customer tenant:
1. Navigate to the Setup home page:
• From an application page, do one of the following:
• Select Setup Home from the Rollbase menu.
• Select Setup Home from the application switcher
• From a setup page, select Setup Home from the application switcher
2. Under the Administration Setup options, select Support Access.
The Support Access page opens.
3. Click Edit to modify the support access settings in your tenant.
4. Select Enable to allow master users to access and log into all the users in your customer tenant.
5. Specify, in the Give Access for field, the duration for which you want to grant the access.
6. Click Save.
Enhanced hashing and encryption algorithms
SHA-512 as Hashing Algorithm
Rollbase has upgraded its password hashing mechanism to SHA-512. Each hashing process combines
plain-text password with random salt generated using cryptographically secure pseudo-random
number generator (CSPRNG). Existing passwords will be re-hashed using SHA-512 after user login.
Encryption Algorithm Private Key
Rollbase supports encryption for text, phone, and email fields, and contents of file upload fields. All these data
are by default encrypted using AES (Advanced Encryption Standard) with 128 bit key size.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 683
Chapter 10: Security and access control
When the system restarts after upgrading to 4.4.4, a private.key file that contains the secret key unique to
your Rollbase instance is generated and saved in your Rollbase config folder on your master machine at
<ROLLBASE_HOME>/config/security.
Note: Store a copy of the generated key in a secure place so that it is available for situations
such as disaster recovery, or machine changes. This file is created and managed by Rollbase and
should not be edited locally.
All fields currently encrypted using default encryption algorithm (AES-128) will continue to function correctly.
They will be decrypted and then re-encrypted using your preferred algorithm and generated secret key the next
time they are edited and saved.
AES-256 Encryption Algorithm Support
Rollbase now also supports encrypting data using AES with 256-bit key size. This is a system wide choice and
managed through the jar file - 'rb_util.jar'.
To make use of AES-256 on a Rollbase Private Cloud:
1. Navigate to the 'rb_util.jar' file in \Progress\Rollbase\pas\rollbase\lib folder.
2. Enter the following command via cmd line.
java -cp
rb_util.jar;jackson-core-asl-1.9.5.jar;commons-io-2.4.jar;commons-codec-1.10.jar;jackson-mapper-asl-1.9.5.jar
com.rb.util.system.SystemKeyGenerator <param1> <param2>
• param1 is the path of the directory where existing private.key file has been uploaded or new
private.key file should be generated.
• param2 is encryption type (default value is 0). If you wish to set AES-128 as default encryption algorithm
for Rollbase instance, use 0. For AES-256, use 1. Currently, Rollbase only supports AES-128 or 256.
Note: Command for a Linux machine is: java -cp
rb_util.jar:jackson-core-asl-1.9.5.jar:commons-io-2.4.jar:commons-codec-1.10.jar:jackson-mapper-asl-1.9.5.jar
com.rb.util.system.SystemKeyGenerator <param1> <param2>
Sample usage for Windows: java -cp
rb_util.jar;jackson-core-asl-1.9.5.jar;commons-io-2.4.jar;commons-codec-1.10.jar;jackson-mapper-asl-1.9.5.jar
com.rb.util.system.SystemKeyGenerator C:\Users\username\Desktop 1
In the above sample, <jackson-core-asl-1.9.5.jar, commons-io-2.4.jar,
commons-codec-1.10.jar, Jackson-mapper-asl-1.9.5.jar> is a list of dependent jars required
to run this utility. Running this utility from the lib folder ensures all required jars are available in current
directory. In case, you do not have commons-codec-1.10.jar present in the working directory,
ClassNotFoundException: at org.apache.commons.codec.binaryStringUtils exception is
thrown. To fix this, you must pull all referenced jars into the current directory, from where commands are
being executed.
3. Based on whether a new file was created or an existing file was updated, the utility returns a final success
message.
Note: If these JCE files are not installed and the ‘EncryptionType’ is set to AES-256, encryption attempts
will fail with the exception: Illegal Key Size.
Important: Support for unique constraint validation on encrypted fields has been deprecated. Thus, unique
checks on encrypted fields will not work. Encrypted fields cannot be audited, marked unique or indexed as part
of the search engine. Once set, this option cannot be removed.
684 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Security for portals
Security for portals
When you create a Rollbase portal, there are several security features you can use. For more information, see
Portal security on page 540.
Enhanced Security and Authentication-related
Features
Here are the enhanced security-related features:
• New user-level security settings on page 685
• Change to authentication fallback behavior on page 688
• Change to conditional field-level permissions when creating records on page 688
New user-level security settings
This release introduces user-level security settings. These include:
• My Security Settings option on the My Profile screen where users can allow/disallow administrators to
log into their accounts to provide support.
• User Permissions settings for roles that gives administrators control over access that was not previously
configurable, such as personal settings and preferences, including the new security setting.
• Support Access screen supports enabling and disabling of the two types of support logins (as an
administrator or as a particular user). It also allows administrators to set a duration for the access.
One result of these changes is that the Administrator of a tenant can enable one or both of the two types of
support logins, and each user can control support access to their own account (unless it is disabled by the
administrator for their role).
My Security Settings option on My Profile screen
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 685
Chapter 10: Security and access control
The My Security Settings option now appears on the My Profile screen:
It opens the My Security Settings screen, where users can enable or disable support access.
User Permissions settings for roles
A new set of User Permissions is now available on the Permissions screen for roles. While they appear on
the user Permissions screen, administrators can only edit them for a role.
These permissions are all enabled by default for every role. Administrators can disable/enable each of these
permissions for a role.
User Permissions include:
686 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Enhanced Security and Authentication-related Features
• My Settings — When disabled, users with that role cannot manage the settings on their My Settings
screen. My Settings will not appear on the My Profile screen.
• My Third Party Settings — When disabled, users with that role cannot manage the settings on their My
Third Party Settings screen. My Third Party Settings will not appear on the My Profile screen.
• My Localization Settings — When disabled, users with that role cannot manage the settings on their My
Localization Settings screen. My Localization Settings will not appear on the My Profile screen.
• Recycle Bin — When disabled, users with that role cannot manage their recycle bin. Recycle Bin will not
appear in the Rollbase menu or on the My Profile screen. See New Recycle Bin option on My Profile screen
• My Security Settings — When disabled, users with that role cannot manage the settings on their My
Security Settings screen. My Security Settings will not appear on the My Profile screen.
• My Theme — When disabled, users with that role cannot set the theme on the My Preferences screen.
The My Theme area will not appear on the My Preferences screen.
• Notifications — When disabled, users with that role cannot edit Notifications on the My Preferences
screen. The Notifications area will not appear on the My Preferences screen.
• Landing Page Configuration — When disabled, users with that role cannot set the Landing Page
Configuration on the My Preferences screen. The Landing Page Configuration area will not appear on
the My Preferences screen.
If My Theme, Notifications, and Landing Page Configuration are all disabled for a role, My Preferences will
not appear on the My Profile page for users with that role.
The following screen shows the My Profile screen for a user whose role does not have permission for Recycle
Bin, My Theme, Notifications, and Landing Page Configuration:
Support Access screen
The Support Access screen, accessed from the Setup Home screen by clicking Support Access from the
Administration Setup area, previously supported only one option, Support Access. In this release, there are
now two options on this screen:
• Login — When enabled, allows administrators from the master tenant to log in to the tenant as an
administrator
• Login As — When enabled, allows administrators from the master tenant to log in and view apps as a
particular user would see them, that is, with the same Role and permissions.
For hosted Rollbase, Progress administers the master tenant. On Private Cloud, login permission applies to
master tenant administrators, but might also apply to ISV Partners and those with custom roles.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 687
Chapter 10: Security and access control
Edit the Give Access for fields to set the duration for which to allow enabled access.
Change to authentication fallback behavior
In this release, the way Rollbase handles fallback for an authentication failure has changed.
In a Private Cloud installation, administrators can configure Rollbase to use an external authentication method
instead of the default password authentication. In previous releases, if authentication with external authentication
method failed, Rollbase would fallback and use the default password authentication. This fallback behavior
only applied to administrative users.
In this release, a user can choose to fallback to the default password authentication if one of the following
applies:
• The user provides the URL parameter adminFallback. When set to true, it enables fallback behavior.
This is only available to administrative users. The following example shows the URL with this parameter:
myrbhost:8830/router/login/loginPrivate.jsp?adminFallback=true
• The tenant uses a custom authentication method and the code from that implementation throws a
FallbackException. This is not restricted to administrators; restrictions depend on the implementation
of the custom authentication method specified by the shared property CustomAuthClass. The following
code shows a custom authentication method that throws FallbackException:
public boolean authenticate(ICustomer cust, String loginName, String password, String
ipAddress,
boolean isAPI, Map<String, Object> additionalData) throws Exception {
...
}
The REST login method has a new URL parameter, adminFallback, that provides the same fallback
behavior for administrative users as the adminFallback URL parameter in the user interface. This parameter
defaults to false; set it to true to enable fallback behavior.
Change to conditional field-level permissions when creating records
Previously, fields with conditional view or edit permissions were hidden on pages where users create records.
In this release, these fields are no longer hidden and Rollbase uses formulas for conditional view and edit
permissions for those fields.
This applies to both view and edit conditional formulas. If the view conditional formula returns true and the
edit conditional formula returns false for a field on a page, the page displays the field but does not allow the
user to enter a value in the field. If the view conditional formula returns false, the field does not appear on
the page.
688 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Enhanced Security and Authentication-related Features
This change might require changes to existing formulas for conditional field-level edit permissions, because
the current record context is empty during record creation. This means that all tokens for the current record
evaluate to null. If you have formulas that use the current record context, for example, the {!id} token, they
will not work during record creation. Other tokens, such as Current User, Current Customer, Settings, and
Helpers, still work.
See Setting field-level permissions on page 659 for more information and example patterns for conditionalizing
formulas.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 689
Chapter 10: Security and access control
690 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
11
Publishing and distributing applications
In Rollbase, you can publish and distribute applications in the following ways:
1. To give others who have an account in your tenant access to an application, assign specific users or user
roles the appropriate permissions. See User authentication on page 644 and Role-based access control on
page 648.
2. To distribute to the Rollbase community for sale or free, publish an application to the Rollbase Marketplace.
See Using the Progress Rollbase Marketplace on page 692 and Publishing to the Marketplace App on page
693.
3. To provide the application to users in other tenants, perhaps used by other groups in your organization,
generate an XML version of the application. Any Rollbase user with a role of Administrator can install the
application in their tenant. See Distributing applications in XML format on page 703 and Generating application
XML on page 708.
For details, see the following topics:
• Using the Progress Rollbase Marketplace
• Distributing applications in XML format
• Troubleshooting published applications
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 691
Chapter 11: Publishing and distributing applications
Using the Progress Rollbase Marketplace
Progress Rollbase Marketplace is an online store where Rollbase users can buy and sell applications. The
application offerings can be free or paid:
• Free applications: Publishers offer their applications free on the Marketplace. Users then directly install
the applications from the Marketplace.
• Paid applications: Publishers offer their applications for a fee on the Marketplace. Users click Learn More
to purchase and install the app from the publisher's Web page. The publisher hosts the application and
manages billing and installation.
See Installing an application from the Marketplace on page 124 for information about installing applications from
the Marketplace.
The Marketplace works a bit differently for hosted and Private Cloud customer tenants:
• Hosted Rollbase users distribute their applications to the Marketplace hosted by Progress. This can be
accessed by all Rollbase users.
• Rollbase Private Cloud master administrators can configure, manage, and rebrand a private Marketplace
(one per Rollbase installation), and distribute their applications only to their users. See Managing the
Marketplace using the Marketplace application in Rollbase Private Cloud on page 697 for more information.
Additionally, Rollbase Private Cloud master administrators who have moved from earlier versions of Rollbase
to Rollbase 4.0 can choose to enable or disable Marketplace in their tenant. For more information, see
Enabling or disabling Marketplace in Rollbase Private Cloud on page 695.
The following diagram shows how users access the Marketplace:
692 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Using the Progress Rollbase Marketplace
Those with access to the Marketplace can navigate to it in the following ways:
• By selecting the Install Applications option from the Rollbase menu.
• By selecting the New Application option from the Rollbase menu and clicking Install from Marketplace.
• From the Marketplace URL:
• Marketplace on Rollbase Private Cloud: http(s)://<host-name>/master/marketplace
Note: You can configure your Rollbase Private Cloud Marketplace URL in Shared Properties on page
786.
• Marketplace on Hosted Rollbase: https://www.rollbase.com/master/marketplace
Publishing to the Marketplace App
For Rollbase Private Cloud installations that have been upgraded from a prior version, by default the Marketplace
will be enabled as the way to publish and distribute applications. However, master administrators can enable
Marketplace and provide it to their customer tenants as an alternative. Progress recommends switching to
Marketplace because it provides a better user experience.
Publishing an application to the Marketplace application makes it freely available for installation in any tenant
in the same Private Cloud instance. By default, a master administrator must approve published applications
before they appear in the Marketplace web page. Private Cloud administrators can change this behavior as
needed by modifying the Published Application object in the master.
To summarize, all applications that are published or unpublished reside in theMarketplace application. Whereas,
when a master approves all the published applications, the applications becomes available in the Marketplace
web page.
If you continue development of an application that has already been published, you can publish updates to that
application. Each updated application will have a higher version number than the last and customers who
installed previous versions will be able to upgrade to the latest version. Private Cloud Master system
administrators can also push updates of an application to all tenants that have installed the applications. See
Pushing application updates to other tenants on page 946.
Publishing an application to the Marketplace is a two-step process:
1. A tenant administrator publishes the application
Tenant administrators use the Publish option on an application’s view page to publish their application.
This submits the application for publishing approval to the administrators of the master tenant.
2. A master administrator approves the submitted application for publication on the Marketplace:
• Progress Software approves applications for the Hosted Marketplace
• Rollbase Private Cloud applications are published to the Marketplace after an administrator of the master
tenant approves them using the Marketplace application (see Approving a published application in the
Marketplace on page 695)
1. From the application switcher:
• To navigate to the settings for the current application, click App Settings.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 693
Chapter 11: Publishing and distributing applications
• To navigate to settings for a different application, hover the mouse pointer over the application and click
the settings icon.
2. Click Publish or Publish Updates. The button name depends on whether the application has been published
previously.
The Publish Application dialog appears.
3. Specify the following:
Note: If this application is approved on the Marketplace, the information you provide here will be displayed
on the Marketplace's application page.
• Version: The version number of the application. Enter an integer value. For example, if you publish an
update to version 1, use 2.
• Application Name: The name of the application
• Tags: The terms assigned to this application. Publishers can use these terms to identify the application
from a group. This is an optional field.
• Category: One of the available categories (on the Marketplace) for this application
• Application Description: Description of the application. This is an optional field
• Application Logo: A custom logo image. The image dimensions are 180x180. The image size must be
less than 512KB.
• Lock Status: The status of the application's component locking mechanism. Unlocked is the default
status
If you select Partially Locked, you must specify which application components to lock by selecting the
relevant check boxes. Expand the tree to specify locking at a fine-grained level. For more information,
see Locking applications on page 706.
• Supported Languages: The languages in which this application can be used. This is an optional field.
• Requires Rollbase: The Rollbase versions required to use this application
• Product Type: The type of application, App or App Template
• Screenshots: The application's screenshots. Typically, you use these screenshots to help Marketplace
users evaluate the application interface and features. A minimum of two screenshots are required to
publish an application.
• Publisher: The publisher-related information. This provides Marketplace users information about the
publisher's headquarters, phone number, email ID, and website information.
• Publisher Description: A short description about the publisher of the application. This is an optional
field.
694 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Using the Progress Rollbase Marketplace
• Advanced Options: The fields in this section are optional. They specify:
• If the application is a Featured or a Paid application on the Marketplace
• Links to Product Overview, Resources, Learn More, and Price Options page. Typically, you use
these links to direct Marketplace users to your website's pages.
• An application Banner
4. Click Submit.
If you submitted to the Rollbase hosted Marketplace application, you will receive notification on the status
of your application.
Additionally, using the Marketplace application, the master administrators can directly publish an application
using its XML file. To do this, they must use the New Published Application option on the Published Apps
menu.
Approving a published application in the Marketplace
In hosted Rollbase, Progress Software is the administrator of the master tenant. So, your applications are
published to the Marketplace after Progress Software approves them.
In Rollbase Private Cloud, master administrators can review and choose to approve published applications to
make it available in the Marketplace web page for Private Cloud installation. When a Private Cloud administrator
submits a published application, the master administrator receives an email with a link to preview and approve
it from the Marketplace application.
Alternatively, the master administrator can execute these steps to approve and publish an application in the
Marketplace:
1. Open the Marketplace application from the application switcher.
2. Click and open Published Applications from the application menu bar. The Published Apps page opens.
3. In the Published Applications grid, under the Published Application column, click the application's name
that you want to approve and publish. The application’s view page opens.
4. Select Edit. The application’s edit page opens.
5. Optionally, update the application properties set by the application submitter and click Marketplace Preview
to see how the application page will appear on the Marketplace web page.
6. Select the Approved check box and then click Update. The application is now available on the Marketplace
web page and the application publisher is notified through an email.
Enabling or disabling Marketplace in Rollbase Private Cloud
If you upgrade Rollbase Private Cloud from a prior version, Application Directory continues to be the platform
to publish and distribute applications. Master tenant administrators can enable Marketplace and provide it to
their customer tenants as an alternative of Application Directory. Marketplace provides more features and a
better user experience to publish and distribute applications.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 695
Chapter 11: Publishing and distributing applications
Enabling Marketplace
The following are the high-level steps for a master tenant administrator to enable and configure Marketplace:
1. Install the Marketplace application. The Rollbase XML file of the application, app4-mkp.xml, is shipped
with the current Rollbase installer. For example, if you installed PAS, and accepted the default settings.
This directory would be <drive>:\Progress\Rollbase\Pas_Instance\rollbase\apps.
The Marketplace application is made available on the master tenant and can be accessed from the
application switcher.
2. Open and configure the Marketplace application:
Note: To configure and administer your Marketplace, you must understand the different sections of the
Marketplace home page (see Managing the Marketplace using the Marketplace application in Rollbase
Private Cloud on page 697).
• Open the Categories object tab and create all the application categories (root, level1, and level 2) to be
displayed on the Marketplace.
Applications in the Marketplace must be associated with a category. Categories that do not have any
associated application will not appear on the Marketplace.
• Open the Published Apps object tab and edit (individually) all the applications in the Published
Applications list.
As part of editing the application, ensure that all the application details are specified appropriately. These
details will be displayed on the Marketplace's application page.
• Open the Carousels object tab and add carousel images to be displayed on the Marketplace home
page.
3. In the System Console > System > Shared Properties > Customize > White Label, open and configure
the MarketplaceURL property to enable Marketplace.
Navigate to and test your Marketplace by selecting the Install Applications option on the Rollbase menu
(on the top-left corner of any Rollbase page).
Enabling the Marketplace does not automatically publish all your Application Directory's applications to the
Marketplace. So, from the Published Apps menu of your Marketplace application, you must identify and
approve the applications that you want to publish on the Marketplace. You can do this using the Published
Apps menu of the Marketplace application (see Approving a published application in the Marketplace on page
695).
Note: Enabling Rollbase Marketplace disables Rollbase Application Directory.
Disabling Marketplace
To enable Rollbase Application Directory, comment-out or do not provide any value to the MarketplaceURL
property in the System Console → System → Shared Properties → Customize → White Label.
Note: Enabling Application Directory disables Marketplace.
After enabling the Application Directory, administrators of the master tenant can access and configure the
Application Directory application from the System Console. All the applications published on the Marketplace
will be available on the Application Directory.
Progress does not recommend using Application Directory over Marketplace.
696 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Using the Progress Rollbase Marketplace
Managing the Marketplace using the Marketplace application in
Rollbase Private Cloud
Rollbase Private Cloud includes the Marketplace application, which master tenant administrators can use to
manage Marketplace. For example, you can can publish applications, define categories, and add carousel
images to Marketplace using this application. You access the Marketplace application from the application
switcher just like other Rollbase applications.
Administrators can manage the following:
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 697
Chapter 11: Publishing and distributing applications
• Published Applications: To manage applications that are available on the Marketplace and those that are
submitted by Rollbase users to be published on the Marketplace.
Additionally, you can use the New Published Application option to publish an application on the Marketplace
using an application's XML file. For information about generating an application's XML file, see Generating
application XML on page 708.
• Categories: To create and manage the application categories displayed on the Marketplace’s home page.
Categories can be organized into root categories and sub-categories. A category consists of the following
properties:
• Category name: Name of the application's category
• Level: Specifies the order in which a category appears in the Marketplace. The value is an integer and
the minimum value is 1.
• Root Category: Specifies the category's root category
• Sub Categories: Specifies the sub-categories for this category
• Enable: Specifies if the application’s category is enabled on the Marketplace
If you disable a root category, all of its sub-categories under it are disabled.
• Ratings: To manage an application's ratings (submitted from by Rollbase users) displayed on the application’s
home page. A rating can only be published from the application's page on the Marketplace. A rating consists
of the following properties:
• Application Reviewed: Identifies the application that was reviewed
• Rating (on a scale of 1-5): Rates an application on a scale of one to five stars, one star being the lowest
rating and five stars being the highest rating
• Review Title: Specifies a headline for the rating
• Review: Specifies the review details
• Reviewer: Identifies the user who reviewed the application
• Approved: Specifies if the rating is approved and published on the Marketplace
• Carousel Images: To create and manage carousel images (the auto-scrolling images on the home page)
that are displayed on the Marketplace's home page. A carousel image has the following properties:
• Carousel Image: Specifies the image name
• Published Application: Specifies the application page to open when a user clicks on the carousel image
• Order: Specifies the order in which the carousel image scrolls, for example, a 1 value for the Order
makes an image appear as the first image on the carousel area of the Marketplace
• Enable: Specifies if the image is approved and published on the Marketplace
• Image: Specifies the carousel image to be displayed
• Flags: To manage the applications that are reported as inappropriate; an application can only be flagged
from its page on the Marketplace.
• Report Abuse: Specifies, from the list of available categories, a category for inappropriateness
• Application being Reported: Specifies the application that is being flagged as inappropriate
698 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Using the Progress Rollbase Marketplace
• Reason: Specifies details about why an application is considered inappropriate
• Reporter: Identifies the subscriber who reported the application being flagged
Rebranding Marketplace
Administrators on the master tenant can rebrand the Marketplace by adding a custom logo to replace the
Progress Rollbase logo.
1. From the application switcher, navigate to the Marketplace application's setup page.
The setup page for the Marketplace application opens.
2. Click Edit.
3. In the Custom Logo field, click Choose File. Browse to the file and click Open.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 699
Chapter 11: Publishing and distributing applications
Note: The custom logo file must be a .gif, .jpg, or .png file.
4. Click Save.
5. Refresh the Marketplace page.
Marketplace is rebranded with your custom logo:
Configuring Marketplace notifications in Rollbase Private Cloud
Marketplace sends emails to its users to notify them of certain statuses. These notifications are set in the
Marketplace application as email templates, which can be customized by administrators of the master tenant.
For more information, see Email templates on page 199.
700 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Using the Progress Rollbase Marketplace
The following table describes when these notifications are sent to users and how to configure them:
Table 4: Marketplace Notifications
Notification Email Timing Notification Recipient Email Template Details
When a publisher submits an The administrators of the master Template Name: Application
application to the Marketplace for tenant Approval Pending
approval.
Template Location: Object
definition page of Published Apps
Default email content:
• Basic application and publisher
details
• A direct link to approve the
application
When an administrator of the Application publisher Template Name: Application
master tenant approves the Approved
application and it becomes available
Template Location: Object
on the Marketplace.
definition page of Published Apps
Default email content:
• Basic application and publisher
details
• A direct link to the application
page on the Marketplace
When a publisher updates a The administrators of the master Template Name: Application
published application. tenant Updated
Template Location: Object
definition page of Published Apps
Default email content:
• Basic application and publisher
details
• A direct link to view the latest
version of the application on the
Marketplace
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 701
Chapter 11: Publishing and distributing applications
Notification Email Timing Notification Recipient Email Template Details
When a user installs a free Application publisher Template Name: Application
Marketplace application. Installed
Template Location: Object
definition page of Published Apps
Default email content:
• Basic application details
• The name of the Rollbase user
who installed the application
from the Marketplace
When a user rating of a Marketplace The administrators of the master Template Name: Rating Approval
application is available for approval. tenant Pending
Template Location: Object
definition page of Ratings
Default email content:
• Basic application details
• The name of the Rollbase user
who submitted the rating
• A direct link to approve the
application rating
When a master tenant administrator Application publisher Template Name: Rating Approved
approves and publishes an
Template Location: Object
application rating.
definition page of Ratings
Default email content:
• Basic application details
• The rating assigned to the
application
When a Rollbase user flags an Application publisher Template Name: Application
application as inappropriate. Flagged
Template Location: Object
definition page of Flags
Default email content:
• Basic application details
• The reason why the Rollbase
user flagged the application as
inappropriate
702 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Distributing applications in XML format
Distributing applications in XML format
A Rollbase application XML file includes the definitions of all components associated with the application, such
as objects, object menus, roles, hosted files, batch jobs and seed records. It is important to understand which
components are included in an application when you publish it or generate an XML. Rollbase also enables you
to republish your applications as you incrementally add new features or modify application functionality. Rollbase
automatically increments the application version number each time you publish or generate an application
XML.
The topics in this section describe application distribution options and best practices:
• Components included in an application XML file on page 703
• Use of original IDs on page 705
• Locking applications on page 706
• Attaching seed records on page 707
• Providing a test drive on page 709
• Testing and verifying application correctness on page 708
Components included in an application XML file
To understand about the component included in an application XML file, you must first understand about the
types of objects in an application.
An application consists of core and dependent objects. When you create a new object for an application, by
default it becomes a core object. Core objects are published and installed with the applications. Dependent
objects are pre-requisites to application installation. So, dependent objects must be installed in a tenant before
the application depending on them is installed. Object relationships and conversion maps are only published
with an application if both the source and destination objects are included in that application, either as core or
dependent objects.
You can explicitly assign dependent objects to an application. Rollbase automatically adds dependent objects
to maintain application integrity in the following cases:
• If a Role is given application permissions, the permissions assigned to that role are published as part of
the application XML. This is because the User object is a dependent object for all applications.
• If any core objects have the Approval attribute, the Approval object will be added as a dependent object.
• If any core objects have the Contact attribute, the Communication Log object will be added as a dependent
object.
• If certain objects are not included as core objects but they are related to the objects included on the application
menu, then those objects will be added as dependent objects.
Note: The dependent objects that Rollbase adds to the application cannot be removed from the application.
The application view lists objects assigned explicitly and those included implicitly through tabs. Explicitly
assigned objects have a Remove action link. Implicitly assigned objects can be removed only after removing
the corresponding tab. For example, if there is an application that has Accounts and Contacts tabs, and the
two tabs are related and the application only explicitly assigns an Account detail object. When this application
is published, it will include the following objects: Account, Contact and Account Detail (without a tab).
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 703
Chapter 11: Publishing and distributing applications
The following table summarizes the conditions under which components are included in the Rollbase application
XML file:
Component Included during publication if:
Object definitions Object belongs to the package
Fields Owning object belongs to the package
Views on page 142 Owning object belongs to the package
Pages Owning object belongs to the package
Templates Owning object belongs to the package
Menus and submenus Owning object (if any) belongs to the package
Relationship definitions Objects on both sides of the relationship belong to the
package
Import maps Owning object belongs to the package
Conversion maps Objects on both sides of the conversion belong to the
package
List View object belongs to the package
Report Owning object belongs to the package
Chart Objects used in X and Y axes belong to the package
Gauge Owning object belongs to the package
Related list Parent object belongs to the package
Report links Report belongs to an object in the package
Lookup fields Lookup object belongs to the package
Related fields Related object belongs to the package
User roles Assigned to the application
Portal Assigned to the application
Hosted files Assigned to the application
Batch jobs Assigned to the application
Progress Data Catalogs Assigned to the application
Workflow processes, actions, and statuses Owning object belongs to the package
Triggers Owning object belongs to the package
704 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Distributing applications in XML format
Component Included during publication if:
Survey questions Owning object belongs to the package
Seed records Assigned to the application
Authentication Profile Assigned to the application
Use of original IDs
When you distribute an application to be installed in other Rollbase tenants, Rollbase creates new IDs for all
application components. Rollbase uses these local IDs to manage application updates. Each application
component and subcomponent has a unique local ID within a tenant, and a unique Original ID, which is
guaranteed to be unique across all tenants.
You must design your application to use original IDs and tokens, not the local ID. For example:
• Use integration codes for picklist items and workflow statuses in formula fields, templates and triggers; do
not use IDs.
• Use template tokens such as Link to View Page {!#LINK.order} or a reference to the id, such as {!id}.
Do not explicitly use IDs in Template Fields or Integration Link Fields (used to build dynamic URLs).
The System Information section of component definitions contains the local ID and the Original ID. To find
a component's Original ID, do the following:
1. From the application switcher, select Setup Home.
2. From the Applications Setup area, click the type of component (For example, Applications, Objects, or
Tabs).
3. Click the name of the component. The component definition displays.
For object subcomponents, scroll down to the appropriate section and click the subcomponent name.
The component's properties displays the System Information section with local and original IDs:
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 705
Chapter 11: Publishing and distributing applications
Locking applications
To protect your intellectual property, you can lock part or all of applications you create. This prevents others
who install the application from changing it and guarantees that future updates will safely overwrite existing
components. Applications, objects, and portals installed from locked applications can only be published and
republished from the tenant in which they were originally developed. If an application is unlocked or partially
locked, those installing it can selectively choose components to install or update.
Application lock options include:
• Unlocked: Administrative users that install the application can modify all components. Progress recommends
this option if you do not intend to provide updates to this application, or if it is critical that your users be able
to modify every aspect of the application.
• Partially Locked: Administrative users that install the application can modify all objects, menus, and portals
except those that are marked as locked. Object subcomponents, such as fields and triggers, can be locked
independently, leaving the parent object unlocked. We recommend selecting this option if you plan to provide
updates to specific components of your app while letting your users modify other components as needed.
• Locked: Administrative users that install the application cannot modify anything. We recommend using this
option if you need to maintain complete control over all aspects of the application from update to update,
and want to prevent your users from modifying it.
The only way to modify a locked component in an application is to log into the tenant where the application is
installed as Support Admin using the Login action from the master tenant. See Working with customer records
on page 825 for information about the Login action.
706 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Distributing applications in XML format
Once installed in another tenant, an application's lock status can only be modified if the publisher modifies or
updates it. For example, the publisher can export the original application in an unlocked state, and an
administrator for the other tenant can update the application using the updated application XML.
Attaching seed records
You can attach object records to your application as seed records. These records will be published and installed
as part of the application. Once seed records are installed, they will not be updated during application updates.
Seed records work best for testing and demonstration purposes. Because you attach records one at a time,
this mechanism is not appropriate for distributing complete data sets.
To attach seed records:
1. From the application switcher drop-down available next to the application name:
• To navigate to settings for the current application, click App Settings.
• To navigate to settings for a different application, hover your mouse pointer over the application and
click its associated Application Settings icon.
2. Scroll down to the Seed Records section.
3. Click Attach Records.
The Record Selector window appears.
Note: A maximum of 400 records can be attached.
4. From the Attach Record drop-down list, select the type of object you want to attach.
5. Click each record you want to add. You can select another type of object without closing the window.
The records will be added to the application if they are not attached already.
6. When you finish adding records, close the Record Selector window.
The seed records will display.
Note: If a System Settings object is attached to the application, an Attach Settings button will be available
to add the settings as a seed record.
Attaching authentication profiles
When exporting an application, you can choose to attach an authentication profile only if you want it to be
imported into the destination tenant.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 707
Chapter 11: Publishing and distributing applications
To attach authentication profiles:
1. From the application switcher drop-down available next to the application name :
• To navigate to settings for the current application, click App Settings.
• To navigate to settings for a different application, hover your mouse pointer over the application and
click its associated Application Settings icon.
2. Scroll down to the Authentication Profiles section.
3. Click Attach Authentication Profiles.
4. From the available list of Attach Authentication Profiles, select the profiles you want to attach.
5. When you finish adding profiles, click Save.
When importing an application,
• The existing Password or OE authentication profiles in a tenant will be overridden with the incoming Password
or OE authentication profiles.
• The default authentication profile of a role will be mapped to the default authentication profile of the target
tenant.
Note: Deselecting an authentication profile is not allowed while importing an application xml.
Testing and verifying application correctness
Before publishing your application, you can generate an Application Tree to verify that your application does
not contain any errors. Due to the mechanics of the publishing and installation process, little information other
than the component's internal ID is available to report errors when they occur. For this reason, the Application
Tree Component allows you to more easily pinpoint and fix problems before they occur by showing components
with errors in red.
Application errors typically occur when a certain component has been deleted, but other components still have
a reference to it. For example, a trigger may have a reference to a deleted conversion map. The application
should not be published until these issues are fixed. Error messages may contain numeric IDs of missing
application elements. See Troubleshooting published applications on page 710 for suggestions on fixing common
errors.
Generating application XML
Those who develop Rollbase applications to sell or for use by other departments in their organization can
distribute the applications as XML files that can be installed in any Rollbase tenant.
To generate an application XML file, follow these steps:
1. From the application switcher drop-down available next to the application name:
• To navigate to settings for the current application, click App Settings.
• To navigate to settings for a different application, hover your mouse pointer over the application and
click its associated Application Settings icon.
2. From the More Actions menu, select Generate XML.
3. Verify that the version number is correct.
708 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Distributing applications in XML format
4. Select a Lock Status. If you select Partially Locked, you need to specify which application components
are locked by checking the boxes next to those components. Expand the tree to specify locking at a
fine-grained level. In the following example, the Account object is locked, the Case object is not.
5. Click Generate XML.
6. Store the XML file locally and verify that it has an .xml extension.
The file is ready to distribute.
Providing a test drive
In private cloud installations application submitters can add the Test Drive capability to Marketplace. With
test drive enabled, users can preview application functionality in read-only mode without logging in. When users
test drive an application, they access it with the Portal User role. In Test Drive mode, users cannot create or
modify data records. Make sure the application contains some meaningful sample data.
To enable Test Drive for an application, an administrator must first create a new tenant where the specific
application is installed. Once the tenant is available, edit the application definition and set permissions for the
Portal User user role to access tabs and objects. When the application is ready, the private cloud administrator
must edit the Published Application record and assign that customer tenant as the Test Drive tenant.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 709
Chapter 11: Publishing and distributing applications
Administrative management of published applications
Rollbase Administrators can manage published applications from the Master Server (see Administration on
page 781 ). The Published Apps tab in the System Console provides controls for updating, deleting, and
performing other actions on published applications.
Because the published application object is itself a Rollbase object, Rollbase Master Server administrators can
define a custom approval process for allowing published applications to appear in the Application Directory.
By default, this is simply done by checking the Approved checkbox field.
Rollbase Master Server administrators can also push new versions of an application to customers who have
previously installed that application. See Pushing application updates to other tenants on page 946.
Troubleshooting published applications
The following table lists some application errors and suggestions on how to fix them. If an application is locked,
the original designer must make the fixes and regenerate the application. If an application is unlocked, those
who installed the application into their own tenant can take corrective action. If you encounter any of the errors
listed below, please ask the publisher to fix them or attempt to fix them yourself before contacting Rollbase
Support.
Component Error Fix
Object with Workflow attribute Default status NNN not found Edit the object and set a default
status.
Relationship Related object definition NNN not Delete the relationship or add the
found missing object definition to the
application.
List view Delete, recreate, or edit and save
List view NNN not found the list view.
View column NNN not found
Portal Web page NNN not found Edit the portal and set its main
page.
Menu Delete or re-create the object,
Object definition NNN not found menu, or page.
Parent menu NNN not found
Page definition NNN not found
Report Edit and save or delete this report.
Object definition NNN not found
Relationship definition NNN not
found
Report column NNN not found
710 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Troubleshooting published applications
Component Error Fix
Chart Edit and save or delete this chart.
Object definition NNN not found
x-axis field NNN not found
y-axis field NNN not found
Conversion Map Object definition NNN not found Delete this conversion map or add
the destination object definition to
the application.
Import Map Object definition NNN not found Delete this import map.
Page Cell Field definition NNN not found Delete this page cell by editing the
page and removing it (this often
requires just opening the page in
the page editor and re-saving the
page).
List Component View NNN not found Use the Page Editor to select the
list component and set its default
view.
List Component Page NNN not found Use the Page Editor to select the
list component and set its
destination view and edit page.
Related List Relationship Definition NNN not Delete this related list.
found
Chart Cell Chart NNN not found Use the Page Editor to select the
chart component and set its default
chart.
Portal Link Cell Page NNN not found Use the Page Editor to remove this
portal cell link and replace it with a
valid one.
Report Link Cell Report NNN not found Use the Page Editor to delete this
report link from the page.
Portal Submission|Log in Form Page NNN not found Use the Page Editor to select the
form component and choose a valid
destination Page.
Grid Control Relationship Definition NNN not Configure or delete the grid.
found
Related Field Relationship Definition NNN not Delete this related field.
found
Lookup Field Relationship Definition NNN not Edit and save the lookup field.
found
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 711
Chapter 11: Publishing and distributing applications
Component Error Fix
Template File Field Template NNN not found Edit or delete this template file field.
Dependent Picklist Field Field Definition NNN not found Edit or delete this dependent picklist
field.
Trigger Edit or delete this trigger - some
Field Definition NNN Not Found elements it relies upon are missing.
Data Map NNN not found
Status NNN not found
Template NNN not found
Workflow Status NNN not found
Relationship Definition NNN not
found
New Record Trigger Target Object with id NNN is not This trigger creates an object which
included into this application is not included into this application
either as a core or a dependent
object.
Workflow Process Edit this process and make sure that
Workflow Status NNN Not Defined the default is set, or delete the
Workflow action NNN not defined process and re-create it.
Workflow Action Workflow Status NNN Not Defined Edit this action and fix the Change
Status To setting.
Workflow Action Page NNN not found Status NNN not Edit this action and choose the
found Relationship Definition NNN correct parameters or delete and
not found Conversion Map NNN not re-create it.
found Template NNN not found
Batch Job Attach the required object definition
Report NNN Not found to the application or remove the
Object Definition NNN not found batch job.
712 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
12
Advanced setup and administration
This section describes the setup and administration options in the Personal Setup, Administration Setup,
Support, and Monitoring Setup pages.
For details, see the following topics:
• Profile Settings options
• Administration setup
• Monitoring setup
• Support
• Language support
• Enabling Google Apps for Rollbase Private Cloud
Profile Settings options
Personal setup is available to all Rollbase users, including those who do not have the Administrator role. Users
can modify personal settings by selecting Profile Settings from the profile menu and selecting the appropriate
option from the Profile Settings page. Administrative users can modify personal settings from either the profile
menu or by selecting the appropriate option from the Personal Setup section of the Setup Home page.
Personal settings are divided into multiple options, with each option on a separate page. These options are:
• MY SETTINGS — Allows you to configure general user settings
• MY PREFERENCES — Allows you to set your default theme and set a landing page
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 713
Chapter 12: Advanced setup and administration
• MY SECURITY SETTINGS — Allows you to enable or disable support access to your account
• CHANGE MY PASSWORD — Allows you to change your password
• CHANGE API CREDENTIAL — Allows you to generate an API token for authentication or change the
password.
• MY THIRD PARTY SETTINGS — Allows you to configure Google app settings
• MY LOCALIZATION SETTINGS — Allows you to set the locale, date and time format, and number format
settings
• MY RECYCLE BIN — Allows you to manage your recycle bin
Administrators can limit access to any of these categories by users with particular roles. See Setting user
permissions for roles on page 661 for more information.
The following topics describe the settings in each category.
My Settings
Selecting My Settings from the My Profile page or from the Setup home page opens the My Settings page.
This page contains fields for editing contact information, login name, and other user preferences and settings.
In addition, you can view or edit the following user preferences and settings:
• Rows Per Page — Specifies the default number of rows per page on record list pages
• Do Not Animate Collapse — Specifies that trees, which can expand and collapse, be collapsed without
the default animation
• Location, Department, Function — Specifies the location, department, and function to which the user
belongs. These values will be copied by default to new records with the LDF attribute created by this user.
See Location/department/function permissions on page 669 for more information. Only an administrator can
change this field.
• Reports To, Direct Reports — Specifies the user's hierarchy that is used for access control. For information
about these settings, see User hierarchy of permissions on page 665. Only an administrator user can change
these settings.
• Approver — Select if this user is allowed to be an approver (see Approvals on page 273). Only an
administrator user can change this field.
• Language and Time Zone — Specifies the language and time zone to be used in your user account.
Note: While a Date Format field is available on this page, setting it has no effect if you are using the New
UI. Instead, Rollbase uses localization settings, including the date format, from the My Localization Settings
page.
• Email Footer: Specifies the footer text to be used in your email messages. This is to personalize your email
messages.
• Email Encoding: Specifies the encoding format of your email messages.
• Google Apps Settings: Specifies Google email account credentials to access Gmail, Google Calendar
and Google Spreadsheets seamlessly with Rollbase apps. For information about integrating Google accounts,
see Integrating with Google applications on page 630.
714 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Profile Settings options
Note: Progress recommends that all customers set their Google Apps Settings from the My Third Party
Settings page. See Providing your Google credentials to Rollbase on page 631 for details.
My Third Party Settings
Selecting My Third Party Settings from the My Profile page or from the Setup home page opens the Third
Party Settings page.
This page lets you configure Rollbase to use your SMTP, Microsoft Exchange, or Gmail email address to send
emails and to view email from those accounts from within a Rollbase application. You can also configure your
third party settings to synchronize your Rollbase calendar with your Exchange or Google calendar, which is a
one-way synchronization from Rollbase to Exchange.
To enable the above options, an administrator must enable them on the Email Server Settings page. By
default, Exchange and Gmail are enabled. See Account administration and security settings on page 728 for
more information.
If you are using Gmail, you might need to enable IMAP on that account. See Enabling IMAP on your Google
account on page 631 for details.
To configure Rollbase to use your email account and sync your calendar:
1. In the Email Options area, select the type of account (SMTP, Gmail, or Microsoft Exchange).
2. In the Calendar Options area, select the type of calendar (None, Gmail, or Microsoft Exchange).
3. Do one of the following:
• For SMTP or Microsoft Exchange, enter your email address and password in the User Name and
Password fields for the selected email and calendar (if using Microsoft Exchange calendar) options.
• For Gmail, click Attach. A popup window opens and prompts you to log in to your account. Click Allow.
4. Click Save.
My Localization Settings
Selecting My Localization Settings from the My Profile page or from the Setup home page opens the My
Localization Settings page. This page lets you set the locale, the date and time formats, and the number
format Rollbase will use in your applications.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 715
Chapter 12: Advanced setup and administration
Note: The date and date-time formats are used on record list and view pages. On edit pages, Rollbase enforces
the basic date formats as defined in Kendo formatting library support. See
http://docs.telerik.com/kendo-ui/framework/globalization/dateformatting#custom-date-formats for more
information.
Note: The number format is used to format Integer and Decimal fields. For Integer fields, select Enable
Grouping when creating or editing the field to use the specified number format on all application pages.
How Rollbase uses localization settings depends on whether you are using the New UI or the Classic UI:
• New UI — Rollbase mandates that the format settings on this page are present and always uses these
values.
• Classic UI — Rollbase first checks if the format settings on this page are present. If they are present,
Rollbase uses these settings. If they are not present, Rollbase reverts to the settings defined on the My
Settings on page 714.
My Preferences
Selecting My Preferences from the My Profile page or from the Setup home page opens the My Preferences
page. On this page, you can set the default theme for all of your applications, configure notifications, configure
a landing page, which is the page (and specified tab). that will open when you log in to Rollbase, and, if enabled
on Rollbase Private Cloud, generate a token for API authentication.
716 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Profile Settings options
Setting the default theme
You can select a default theme that will be used for all of your applications:
Themes are only available in the New UI. For more information about themes, see Working with themes on
page 455.
Configuring notifications
You can configure whether Rollbase will notify you before a session expires and/or before leaving a dirty form
(New, Edit) page: If either of these options is deselected, you will not receive that type of notification.
Configuring a landing page
By default, when you log in to Rollbase after logging out, the last page you visited opens and the menu you
last selected is selected. Administrators can set a landing page for a role. When a user with that role logs in
to Rollbase after logging out, the configured landing page and tab open. See Assigning a landing page to a
role on page 656 for details. You can override these behaviors by configuring a landing page specifically for
your account. You can specify one of the following:
• Default — The landing page and menu for your role, if configured. If it is not configured, the last visited
page and menu.
• Land on last visited tab — The application and menu that were open when you last logged out
• Assign landing page — The application and menu you select
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 717
Chapter 12: Advanced setup and administration
My Security Settings
Selecting My Security Settings from the My Profile page or from the Setup home page opens the My Security
Settings page.
On this page, you can enable or disable support access to your account.
Change My Password
If a user is allowed to change his password for UI password, the Change Password page will be visible. This
page will allow password change for both UI and API authentication profiles.
Selecting Change My Password from the My Profile page or from the Setup home page opens the Change
Password page, which allows you to change your password.
You must type in the old password and the new password (twice) to change your password. The new password
must conform to the password requirements selected for your tenant. For information about security and access
control, see Security and access control on page 643.
Change API Credential
The CHANGE API CREDENTIAL option will appear in the Profile Settings page if:
• The authentication profile is different for UI and API authentications and the password can be managed for
both.
• The authentication profile is different for both UI and API authentications and the password (Password, API
Token, or Custom) can be managed only for the API authentication profile.
Generating API token for authentication
If an administrator has enabled API tokens for authentication, you can generate a token on this page. Once
you generate and save a token, use that token in REST and SOAP login APIs instead of providing your password.
For more information about API authentication, see API authentication on page 866.
Note: A user who has never set the API password can use this page and provide a new password while leaving
the old-password text field as blank.
To generate a token:
718 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Profile Settings options
1. Click Generate Access Token. The API Token field is populated with the token.
2. Copy this token and use it in any login API as the value of the password parameter.
Note: You must copy and save the API Token value in a secure place for further use. You cannot retrieve
this value once you navigate away from the Change Password page.
3. Click Save.
You can regenerate the token at any time. The new token replaces the previous one.
My Recycle Bin
Selecting Recycle Bin from the My Profile page or from the Setup home page opens the Recycle Bin page.
This page allows you to select deleted items to purge and/or restore. This is the same page accessed by
clicking Recycle Bin in the Rollbase menu.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 719
Chapter 12: Advanced setup and administration
Administration setup
The Administration Setup page enables administrators to mange user accounts, security, backup, and
tenant-specific settings such as currency codes and exchange rates. You can access it from the application
switcher, Setup Home > Administration Setup.
Settings on the Administration Setup page apply per tenant. This page contains the following sections:
• User Administration: Links to manage system-wide settings (see Using company-wide settings on page
726) as well as users and their roles. The following options are available under user administration:
• Users: Opens a view of user records with controls for creating and managing user accounts.
• Roles: Opens a view of Role records, with controls for creating and managing user roles. For more
information, see Creating and editing user roles on page 650.
• Transfer Owners: Opens the Transfer Ownership dialog with controls for changing the user related
to a particular object. For more information, see Transfer owners on page 726.
• Account Administration: Links to administer organization account and company-wide settings.
• Settings: Opens a view of company-wide settings shared between objects and applications. For more
information, see Using company-wide settings on page 726.
• Account Settings: Opens the Edit Account Settings dialog with account information, administrative
contacts, page appearances, default account settings, and language settings. For more information, see
Account settings on page 727, and Account administration and security settings on page 728.
• Currency Codes: Specify the type of currency for a particular record (e.g., Invoice). Enter a list of
currency names and currency codes you would like to support. Mark the currency used in your
book-keeping as the default by prefixing it with the symbol {D}. For example:
{D}US Dollar|USD
• Exchange Rates: Opens a view to set exchange rates. For each relevant date, enter exchange rates
as decimal numbers between your selected base currency (typically your bookkeeping currency) and
the other supported currencies you defined earlier. Learn how to enable multi-currency support .
• Email Server Settings: Opens a view to configure custom SMTP server settings. For more information,
see Account administration and security settings on page 728.
• Preferences: Opens a view for administrators to configure various preferences such as New UI, general
preferences, email settings, notifications, pdf parser and dynamic image resize. See Configuring
Administrative Preferences on page 721 for detailed information.
• Localization Settings: Opens a review to set organization's localization settings such as locale, number,
date, and time formats.
• Google Account Setup: Specifies Google OAuth settings of your Google Project. This is a customer-level
setting. You must set this only if you do not want to use the Google Apps settings set by the administrator
of your master tenant.
You can create and customize your Google project (see Enabling Google Apps for Rollbase Private
Cloud on page 753 for information about creating a Google project and acquiring its Client ID and Client
Secret Key), and then specify the Client ID and Client Secret Key values here, which will be used by
all the users (in your customer tenant) when integrating their Google accounts with Rollbase. Type the
Google Map API key to integrate maps with the Rollbase application.
720 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Administration setup
For example, if you are a Rollbase Hosted Cloud customer, and you use Use Default Settings in this
page, then you and all your user will be using the Google Apps settings set by Progress Rollbase. If you
want all your users to use your own Google Apps settings, then you must select the Use Following
Google OAuth Credentials in this page and specify a Client ID and Client Secret key of your personal
Google project.
• Security Settings: Links to manage account security.
• Whitelist: Opens a view to specify a Whitelist of IP Addresses. For more information, see Whitelist IP
addresses on page 645.
• Authentication: Opens a view to specify users' authentication method (Rollbase Private Cloud only).
For more information, see Creating an Authentication Profile on page 838.
• Support Access: Opens a view that you can use to enable a support personnel to access a customer
tenant. For more information, see Enabling an administrative user to log into a customer tenant on page
683.
• Backup and Maintenance: Links to manage backups and account maintenance. The following options are
available under backup and maintenance:
• Backup: Opens a view to create and download a full backup of all your data. For more information, see
Moving and restoring customer tenants on page 828 and Backup and restore on page 730
• Batch Jobs: Opens a view to manage scheduled jobs for email reports, automating backups via FTP,
and automating export of a specific subset of data via FTP. For more information, see Batch jobs on
page 736.
• Global Text Search: Opens a view to manage the full-text search index and view related log files. For
more information, see Global text search on page 738.
Configuring Administrative Preferences
This page is available to both master and tenant administrators to manage run-time activities not related to
application development.
New UI Settings
This section displays settings that are specific to the New UI, which an administrator might want enable for the
user(s).
When the EnableNUIForAll shared property is not selected and/or the AllowClassicUIForNewTenants is
selected, these three options will be visible for individual users to switch between oldUI and NewUI. When the
EnableNUIForAll shared property is selected, these three options will not be visible to the individual users.
• New UI is enabled for me (<current user>): To enable NewUI for current user
• New UI is enabled for the following users: Select individual user(s) from current tenant and enable NewUI
• New UI is enabled for everyone: When this option is selected, the NewUI is enabled for all users under
this tenant. When this option is selected the above two options will be disabled.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 721
Chapter 12: Advanced setup and administration
• Allow users to set individual theme preference: As this preference indicates, select this preference so
that all users, including non-administrative users, can select a theme to use for all applications, regardless
of the theme chosen for each application by an administrator.
Themes are only available in the New UI. For more information about themes, see Working with themes
on page 455and Selecting a theme for a user for more information.
• Revised Grid Control: Select this option to enable the revised grid control for all the users under this tenant.
See Revised Grid Control to understand its usage.
General preferences
• Run custom field validation in API calls:: Select this option to validate any custom fields added to the
API calls.
• Run field validation for Update Field Value trigger: Select this preference to allow customers to run field
validations when the Update Field Value trigger is executed. By default, this preference is enabled.
• PdfFontFamily: Add and configure more fonts to support different languages (For eg- Droid Sans Fallback
for Chinese). You can update the value of this field with desired fonts. If a preferred font value is specified,
it will be used to generate the pdf. Alternatively, if a preferred font value is not specified, then the value
specified in the Shared Properties will be used.
The font-family mentioned in this field is considered as the defualt font. Lato, Helvetica, Arial, Tahoma and
sans-serif are available as default fonts.
722 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Administration setup
Notifications
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 723
Chapter 12: Advanced setup and administration
• Notify before session expiration:: You can configure whether session expiration notifications are sent at
both the tenant and the user level. By default, the user settings is the same as the tenant setting. However,
after you change the setting at the user level, that setting takes precedence for you; if an administrator
changes the tenant setting, it has no effect on the user setting.
• The maximum inactive period after which a session will timeout and expire
• The maximum allowed session time after which a session expires and the user must re-login
• Tenant level — From Setup Home, click Preferences under Administration Setup. Notify before
session expiration is selected by default. Deselect this to turn off notifications at the tenant level.
• User level — From the user profile menu, select My Profile and then select My Preferences. Notify
before session expiration is selected by default. Deselect this to turn off notifications at the user level.
724 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Administration setup
On Rollbase Private Cloud, the default session times are configurable for each security level by modifying
the following properties in the configuration file securityLevel.xml:
• inactiveSessionExpireMins
• loginSessionExpireMins
See Built-in security levels on page 844 for details.
The method hasSessionExpired() returns true if the user session has expired and returns false if
the user session has not expired.
Note: This behavior is only available for users who are using the New UI. It is not available on setup and
administrative pages.
• Notify on leaving a dirty form page: Select this option to configure so that Rollbase will notify you before
a session expires and/or before leaving a dirty form (New, Edit) page: If either of these options is deselected,
you will not receive that type of notification.
Email Settings
When an administrator adds a new user to a Rollbase tenant, Rollbase automatically sends a welcome email
to the user's email address. A new tenant-level preference allows administrators to suppress welcome emails
for new users, also known as silent onboarding. This preference is available on both hosted Rollbase and
Rollbase Private Cloud. It is particularly useful for Private Cloud tenants that use SAML or Kerberos for
authentication.
PDF Parser
To parse and analyse PDF documents select one of the following - Default, Aspose Parser or System Parser.
Dynamic Image Resize Settings
The smart image feature provides automatic resizing of images:
• Select Enable resizing and storing images for different device form factors to specify a maximum size
in Image Upload field properties, so that Rollbase automatically resizes images when users upload them.
• Enable a dynamic image preference that causes Rollbase to automatically store images that are 992px or
wider in four pre-defined widths (992px, 768px, 480px, and 50px) and to render the appropriate image. For
example, on record list pages, Rollbase uses the smallest image, but for view pages and pages that display
cards, Rollbase uses the image closest to but smaller than the device. The dynamic image preference
applies to all apps in a tenant. Images narrrower than one or more of the pre-defined widths will be stored
in the original size and the narrower widths. For example, an image with a width of 500px would be stored
at 500, 480, and 50.
• To have Rollbase automatically resize images on upload, use the Image Upload field property Maximum
Image Size and specify a value in pixels under Shared Properties > Images. For landscape images, Rollbase
applies the maximum size to the width. For portrait images, Rollbase applies the maximum size to the height.
When Maximum Image Size is specified, Rollbase ignores the Maximum File Size property. Rollbase resizes
images only if they are larger than the specified value
Note: When you set the field property or preference, it applies to images uploaded after the setting, not to
previously stored images.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 725
Chapter 12: Advanced setup and administration
Transfer owners
Use the Transfer Owners option in the Administration Setup page to change relationships between a selected
user and records of another type to a different user. To transfer owners, click the Transfer Owners option and
specify the following:
Warning: There is no easy way to roll back these changes, other than editing each record one-by-one.
Do not use this option for temporary reassignments.
• Relationship: Specifies one or more relationships that you want to change between the User object and
other objects (ownership of accounts, cases, etc.)
• Current Owner: Specifies the user you want to reassign records from
• New Owner: Specifies the user to assign the records to
Rollbase replaces the current owner with the new owner for the selected relationships.
Using company-wide settings
This section describes how to manage a set of custom fields that represent system or customer-wide properties
(rather than object-specific properties) that can be used in a number of areas throughout all your applications
such as templates and formula fields and can be conveniently changed from one central location. Examples
of such fields may be tax rate, your marketing slogan, etc.
If you use settings fields in an application, you must include the Settings object in the application before
publishing it.
The Settings object is a singleton object, which means it has exactly one record. You cannot create or delete
that record. Attempting to create or delete a Settings record results in an error notification. For example, the
following screen shows the error notification that appears if you attempt to create a Settings record:
To view or edit company-wide settings, do the following:
1. From Setup Home > Administration Setup > Settings > Configure, define the components of the settings
object.
2. Select Edit to set/modify values the settings object. And then click Save. The Settings object view page
opens.
3. In templates and formulas, from the Template Helper, select the Settings field (from the Helpers group)
and choose the company-wide setting you want to modify:
Calculating sales tax example
This section describes with an example how to create company-wide settings to implement sales tax rates that
are different in different states of a country. To do so you can create company-wide settings in the following
way:
726 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Administration setup
Create two fields in the Settings object for the two different states:
Setting Name Integration Code Value
California Tax ca_tax 7.25
Arizona Tax az_tax 6.60
Then, if you identify each state with its code, implement the sales taxes differently for the different states using
their state code. This can be done using the below formula:
switch ("{!state#code}") {
case "CA": return {!#SETTINGS.ca_rate};
case "AZ": return {!#SETTINGS.az_rate};
default: return 0;
}
The following are the advantages of using settings rather that substitute values into formula directly:
• You can change settings in a single convenient place with controlled access.
• You can publish your formula without referring to specific values.
Using scripts to change setting fields
You can change Settings fields using server-side script the same way you would change data records. Use
{!#SETTINGS.id} token for record's ID:
rbv_api.setFieldValue("$SETTINGS", {!#SETTINGS.id}, "ca_rate", 8.25);
Account settings
You can access account settings from the application switcher, Setup Home > Administration Setup> Account
Settings.This link will take you to the Rollbase Support Portal, where you can change some settings for your
tenant and customize certain aspects of your Rollbase appearance (colors, sidebar components, etc). The
following describes the options on the Account Settings page and how they can be used in your tenant:
• Account information: Specifies your company information. This can be used for display purposes.
• Company Name: Specifies the name of your company.
• Company Logo: Specifies the company logo, which must be rendered in the upper-left corner of Rollbase
pages. If your company logo is uploaded, then it will be used as the default logo in the applications.
• Company address information: Specifies the address of your company. This can be used in your
template and formula fields.
• Administration contact: Specifies the name, email, and phone number of the administrator of the tenant.
This can be used in your template and formula fields.
• Appearance: Specifies the appearance of your Rollbase account.
• CSS Stylesheet: Specifies the stylesheet to be used in your Rollbase tenant. You can choose between
standard Rollbase CSS and custom CSS. Your custom CSS must be upload as a Hosted File (see
Hosted files on page 547)
• Page Components: Specifies which components appear in the sidebar and header on all Rollbase
pages. For example, if you un-check the Create, you will not see the Create section on the sidebar.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 727
Chapter 12: Advanced setup and administration
• Hide Sidebar: Specifies if the sidebar must be hidden for all non-admin users.
• Show Application Tree: Specifies if an application switcher must be show as a tree instead of a switcher.
• Use New UI: Specifies, starting with Rollbase 4.0, if the Rollbase pages must use the new user interface
(introduced in Rollbase 4.0) instead of the classic UI. This option is not available to new Rollbase 4.0
administrative users because the new UI provides a better user experience.
• Use New UI for Admin Only: Specifies, starting with Rollbase 4.0, if the Rollbase pages for administrators
must use the new user interface (introduced in Rollbase 4.0) instead of the classic UI. This option is not
available to new Rollbase 4.0 administrative users because the new user interface provides a better
user experience.
• Default Settings: Specifies the data, time, email encoding, and log settings of your Rollbase account.
• Date format: Specifies the default date format. All the users can override the default settings using the
options on the personal setup page.
• Time Zone: Specifies the default time zone. All user can override the default settings using the options
on the personal setup page.
• Email Settings: Specifies the default email account to be used to send emails, the default email footer,
and email encoding settings. The Default Email Sender is used as the "Reply To" address whenever
Rollbase sends an email that was not invoked by a specific user's email address.
• Security Level: Specifies the security and access control mechanism (see Security and access control
on page 643).
• Expiration Policy: Specifies the number of days before user passwords expire (see Security and access
control on page 643).
• Detailed Log: Enables detailed system loggings of users' activities and API calls.
• Language Settings: Specifies the base and additional languages supported in the Rollbase account. See
Language support on page 740 for details.
Account administration and security settings
You can specify the following account administration and security settings for your tenant:
• Multi-Currency Support:
This page enables you to manage currency names and codes. For information about multi-currency support,
see Multi-currency support on page 349.
• Email Server Settings:
This page enables you to configure the email account that will send administrative messages from Rollbase.
By default, Default Settings is selected, which uses the email server settings set by the administrator of
the master tenant. You can configure Rollbase to use one of the following types of accounts:
• Gmail — See Integrating with Google applications on page 630 for details.
• Microsoft Exchange — To configure an Exchange account:
1. Select Microsoft Exchange.
2. Enter the Exchange email address in the User Name field.
3. Enter the Exchange password in the Password field.
4. Enter an auto-reply email address in the Auto-Reply Address field.
728 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Administration setup
5. Before you can save the settings, you must test them by sending a test email message to a different
email address. Enter the email address to which you want to send the test message in the Email
Address field and click Test Settings.
6. A pop-up dialog opens. After sending the message, Rollbase displays a message stating that the
message was sent. Verify that the email was received and check Message Was Received in Mailbox
to enable the Save option. If the email was not received, reconfigure your email server settings and
try again.
7. Click Save.
• SMTP — To configure an SMTP account:
1. Select SMTP.
2. Edit the following email server settings: Host Name, Port Number, Encryption (select None if your
email server is not enabled for SSL & TLS encryption), User Name (Email ID), Password (Email
password), and a default Auto-Reply Address.
This email address is used for all administrative email communication in your tenant.
3. Test your email server settings by specifying a sample email address and then clicking Test Settings
to see if a sample email message is received at the specified email address.
A pop-up dialog opens. After sending the message, Rollbase displays a message stating that the
message was sent. Verify that the email was received and check Message Was Received in Mailbox
to enable the Save option. If the email was not received, reconfigure your email server settings and
try again.
4. Click Save.
To allow your users to communicate using their email addresses, one or more of the following check boxes
must be selected. Gmail and Exchange are selected by default.
• Allow User Gmail Account
• Allow User Exchange Account
• Allow User SMTP Account
After the required check box is selected, all the users in your tenant can configure that type of personal
email from their Third Party Settings page (see My Third Party Settings on page 715).
For Rollbase Private Cloud customers, email server settings are updated in the Shared Properties.
• Google Apps Settings:
Specifies Google email account credentials to access Gmail, Google Calendar and Google Spreadsheets
seamlessly with Rollbase apps.
• Authentication:
This page enables you to configure your tenant to accept and perform external calls requested by an
authenticated user. For information about user authentication, see User authentication on page 644.
• Whitelist of IP Addresses:
This page enables you to apply an additional security measure. You can specify whitelist of IP addresses
to be checked when user logs in. For information on security and access control, see Security and access
control on page 643.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 729
Chapter 12: Advanced setup and administration
Backup and restore
As hosted Rollbase is a fully managed Software as a Service (SaaS) solution, Rollbase handles data backup
and other disaster recovery solutions. However, you can protect yourself from inadvertent data losses, such
as unintentionally deleted records, objects, or applications, by scheduling system backups.
Only administrators can perform backups. Only one backup file per tenant can be created per 24-hour period
for performance reasons. Rollbase allows customer tenants to take ten backups per month and stores up to
seven copies of the most recent backups. Hosted Rollbase users can contact Progress Support to change the
number of backups per month limit for a customer tenant.
The process of creating a backup file runs asynchronously and uses a queue. You receive an email when the
backup is completed and ready to be downloaded. A full backup is in a compressed (ZIP) file that contains:
• Relational data, all system tables with data as CSV files (one CSV per object definition).
• Binary data, all hosted files, file templates, and images.
Hosted Rollbase enforces a 1 GB limit for your backup data. Note that your backup file might not include the
uploaded file templates, images, and hosted files if your storage exceeds the specified limit. For example, if
you have 500 MB of relational data and 800 MB of hosted files, then Rollbase creates a backup file with only
500 MB of relational data. It does not back up the hosted files.
To back up more than 1 GB of data (relational data and hosted files), you can configure and manage data
backup using your own Amazon S3 cloud storage account or you can contact Rollbase customer support to
resize your 1 GB data backup limit.
Rollbase Private Cloud sets the backup data limit to 20 MB per customer tenant. As an administrator of the
Rollbase master tenant, you can reset the 20 MB limit using the StorageUsageLimitForBkp property value
in the Shared Properties file. The StorageUsageLimitForBkp property value specifies the backup data
limit for all the customer tenants. If you want to specify a different backup data limit for a particular customer
tenant, you must Edit the customer record and update the Max Backup File Storage (MB) field with the
different backup data limit. This backup data limit specified in the customer record overrides the backup limit
set in the Shared Properties.
Rollbase Private Cloud sets the maximum backups per month limit to 10 per customer tenant. As an administrator
of the Rollbase master tenant, you can reset this limit using the MaxBackupsPerMonth property value in the
Shared Properties. The MaxBackupsPerMonth property value specifies the maximum backups per month
limit for all the customer tenants. If you want to specify a different limit for a particular customer tenant, you
must Edit the customer record and update the Max Backups Per Month field with the different limit. The limit
specified in the customer record page overrides the maximum backups per month limit set in the Shared
Properties.
For more information about Shared Properties and working with customer records, see Shared Properties
on page 786 and Working with customer records on page 825.
Backup
Follow these steps to create and download a backup file for your tenant:
1. Navigate to the Setup Home page from the application switcher.
2. In the Administration Setup area, click Backup.
3. To create a backup file, click Create New System Backup.
4. After the backup is complete, click Download to download the backup file to your local machine.
On Rollbase Private Cloud, an administrator on the master tenant can back up a customer tenant. See Working
with customer records on page 825 for more information.
730 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Administration setup
Additionally, you can click View Backup Log to view all the data backup activities performed.
Restore
If you are using hosted Rollbase, or if you are using Rollbase Private Cloud and you want to restore the master
tenant, you must contact Rollbase customer support to restore your data from a particular backup file.
If you are using Rollbase Private Cloud, an administrators on the master tenant can restore data to a customer
tenant from a backup file.
Follow these steps to restore a customer tenant:
1. Acquire a backup file from your customer.
2. Open the System Console application.
3. Select the Customers tab.
4. From the Customer List table, click the name of the customer tenant to restore.
5. From the More actions menu, select System Backup & Restore:
6. Click Upload System Backup.
7. Click Browse to select the required backup file.
8. Click Submit to restore data from the backup file. When the restore is complete, you will receive an email
from Rollbase.
Note: The restore operation erases any changes made since the backup file was created.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 731
Chapter 12: Advanced setup and administration
If you are an ISV and/or are using Rollbase Private Cloud, and you want to use third-party cloud services for
storage, see Using a third-party cloud service for storage on page 942.
Note: When the backup or restore action is in progress, you will not be able to create another backup.
Currency formats
Every currency field and every formula field that returns a value of type Currency allows the selection of a
currency format to use (this field-specific format is used for all users) as shown below:
Note: If your object supports the Multi-Currency attribute, you can create a base currency field that corresponds
to each currency field to automatically calculate that field's value in the base foreign currency. You can also
select the base currency format. See Multi-currency support on page 349.
The table below lists the available currency formats:
Currency Name Currency Code Format(s) Output
United States Dollar USD $ ###,###,###.## $123,000.50
$ #########.## $ 123000.50
$ ###.###.###,## $ 123.000,50
$###.###.###,## $123.000,50
### ### ###,## US$ 123 000,50 US$
$###,###,###.## $123,000.50
US$###,###,###.## US$123,000.50
$###,###,### $123,000
Euro EUR € ### ### ###.## € 123 000.50
###.###.###,## € 123 000,50 €
###'###'###,## € 123'000,50 €
€ ###.###.###,## € 123.000,50
€#########,## €123000,50
732 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Administration setup
Currency Name Currency Code Format(s) Output
### ### ###,## € 123 000,50 €
€###.###.###,## €123.000,50
€ ###,###,###.## € 123,000.50
€###,###,###.## €123,000.50
Pound Sterling GBP £###,###,###.## £123,000.50
£###,###,### £123,000
### ### ###.## 123 000.50
Australian Dollar AUD A$###,###,###.## A$123,000.50
$###,###,###.## $123,000.50
New Zealand Dollar NZD $###,###,###.## $123,000.50
Brazilian Real BRL R$###.###.###,## R$123.000,50
Chilean Peso CLP $###.###.### $123.000
Mexican Peso MXN $###,###,###.## $123.000.50
Canadian Dollar CAD ### ### ###,## $ 123 000,50 $
$###,###,###.## $123,000.50
Chinese Yuan CNY ¥ ###,###,###.## ¥ 123,000.50
¥###,###,### ¥123,000
Hong Kong Dollar HKD HK$###,###,###.## HK$123,000.50
Indian Rupee INR ₹###,###,###.## ₹123,000.50
₹ ###,###,###.## ₹ 123,000.50
₹ ##,##,##,###.## ₹ 12,34,000.50
₹##,##,##,###.## ₹12,34,000.50
Indonesian Rupiah IDR Rp###.###.### Rp123.000
Thai Baht THB THB###,###,###.## THB123,000.50
Singapore Dollar SGD $ ###,###,###.## $ 123,000.50
$###,###,###.## $123,000.50
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 733
Chapter 12: Advanced setup and administration
Currency Name Currency Code Format(s) Output
Japanese Yen JPY ¥ ###,###,### ¥ 123,000
¥###,###,### ¥123,000
South Korean Won KRW ₩###,###,### ₩123,000
Malaysian Ringgit MYR RM ###,###,###.## RM 123,000.50
RM###,###,###.## RM123,000.50
Pakistani Rupee PKR Rs###,###,### Rs123,000
Rs ##,##,##,### Rs 12,34,000
Philippine Peso PHP ₱###,###,###.## ₱123,000.50
###.###.###,## ₱ 123.000,50 ₱
Taiwan New Dollar TWD NT$###,###,###.## NT$123,000.50
Czech Koruna CZK ### ### ###,## Kč 123 000,50 Kč
Hungarian Forint HUF ### ### ###,## HUF 123 000,50 HUF
Danish Krone DKK kr.###.###.###,## kr.123.000,50
kr###.###.###,## kr123.000,50
###.###.###,## kr. 123.000,50 kr.
Norwegian Krone NOK kr ### ### ###,## kr 123 000,50
### ### ###,## kr 123 000,50 kr
Russian Ruble RUB . ###,###,###.## . 123,000.50
. ### ### ###,## . 123 000,50
### ### ###,## . 123 000,50 .
Polish Zloty PLN ### ### ###,## zł 123 000,50 zł
Swedish Krona SEK ### ### ###,## kr 123 000,50 kr
Swiss Franc CHF ###'###'###.## CHF 123'000.50 CHF
CHF ###'###'###,## CHF 123'000,50
CHF ###'###'###.## CHF 123'000.50
CHF ### ### ###.## CHF 123 000.50
734 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Administration setup
Currency Name Currency Code Format(s) Output
Turkish Lira TRY ###.###.###,## 123.000,50
Israeli New Sheqel ILS ###,###,###.## ₪ 123,000.50 ₪
South African Rand ZAR R###,###,###.## R123,000.50
R### ### ###,## R123 000,50
Kazakhstani Tenge KZT ### ### ###,## ₸ 123 000,50 ₸
Belarusian Ruble BYR ### ### ### p. 123 000 000 p.
p.### ### ### p.123 000 000
Kyrgyzstani Som KGS ### ### ###,## 123 000,50
Moldovan Leu MDL ###.###.###,## L 123.000,50 L
Ukrainian Hryvnia UAH ### ### ###,## ₴ 123 000,50 ₴
Bulgarian Lev BGN ### ### ###,## лв. 123 000,50 лв.
Croatian Kuna HRK ###.###.###,## HRK 123.000,50 HRK
Georgian Lari GEL ### ### ###,## GEL 123 000,50 GEL
GEL ### ### ###,## GEL 123 000,50
Romanian Leu RON ###.###.###,## RON 123.000,50 RON
Serbian Dinar RSD ###.###.### RSD 123.000 RSD
Saudi Arabian Riyal SAR ###,###,###.##لایر 123,000.50لایر
SAR###,###,###.## SAR123,000.50
Iranian Rial IRR لایر###,###,###.## لایر123,000.50
IRR###,###,###.## IRR123,000.50
Kuwaiti Dinar KWD ###,###,###.## ك 123,000.50 ك
KWD###,###,###.### KWD123,000.50
Iraqi Dinar IQD ###,###,###.## ع.د 123,000.50 ع.د
IQD###,###,###.### IQD123,000.50
Tunisian Dinar TND ###,###,###.## TND 123,000.50 TND
TND###,###,###.## TND123,000.50
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 735
Chapter 12: Advanced setup and administration
Currency Name Currency Code Format(s) Output
Algerian Dinar DZD ###,###,###.## DZD 123,000.50 DZD
DZD###,###,###.## DZD123,000.50
Jordanian Dinar JOD ###,###,###.## JOD 123,000.50 DZD
JOD###,###,###.## JOD123,000.50
Qatari Riyal QAR ###,###,###.## لایر 123,000.50 لایر
QAR###,###,###.## QAR123,000.50
United Arab Emirates AED ###,###,###.## إ.د 123,000.50 إ.د
Dirham
AED###,###,###.## AED123,000.50
Moroccan Dirham MAD ###,###,###.## م.د. 123,000.50 م.د.
MAD###,###,###.## MAD123,000.50
Other Other ### ### ###.## 123 000.50
### ### ### 123 000
###.###.###,## 123.000,50
### ### ###,## 123 000,50
Batch jobs
Rollbase batch jobs (similar to Oracle Cron jobs) can be used to schedule periodic system maintenance,
notification, and integration tasks. Batch jobs use the permissions set on each object for the Query API.
To create a new batch job:
1. From the application switcher, select Setup Home > Administration Setup> Batch Jobs.
2. Click New Batch Job.
3. Select one of the following options and select Next:
• System Backup:
This job generates a system backup file. Optionally, it can upload the backup file to a remote FTP server.
FTP retry feature will be enabled for this batch job if you select the System Backup Properties > Upload
Backup File To FTP option.
• Data Maintenance:
This job runs specified the specified object script from the Rollbase client-side API on each record of
the selected type.
• Generate Report:
736 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Administration setup
This job runs the selected report and sends it as an email attachment to the specified recipient.
• FTP Data Snapshot:
This job takes a snapshot of report data and uploads it via FTP to a remote server in CSV, XLS, XLSX
or XML format. By default, this batch job has FTP retry feature enabled.
• Re-index Search Data:
This job re-creates the index used for global text search.
• Scheduled FTP Import:
This job uploads spreadsheet file from a remote FTP server and starts the import process defined in the
selected import map. By default, this batch job has FTP retry feature enabled.
Note: FTP retry will be initiated only when one of the the following exceptions or failures occur — connection
to host failed, login failed, uploading file failure, downloading file failure, deleting file failure, and changing
directory failure. By default, the number of FTP retries allowed is 5. The default value of retry interval is
3000(ms) and you can modify this value by changing the RetryTaskTime shared.property.
4. Enter the job-specific settings. Settings common to all job types include:
• Job Name
• This batch job is deployed. Uncheck to save the batch job settings but disable the batch job from
running.
• Start At
• Repeat Every (the period of time between runs, with a one day minimum)
• Notify Address
5. Click Save.
Managing Batch Jobs
Navigate to Setup > Administrative Setup > Batch Jobs to see the list of existing Batch Jobs. From the list
of current Batch Jobs you can perform the following:
• Click New Batch Job to create a new job.
• Click Queue to see all scheduled jobs.
• Click API Permissions to view Server API role permissions. Batch jobs use the permissions set on each
object for the Query API. To change Server API permissions, click Edit Permissions.
• Click Jobs Log File to view the job log.
• Click Restart All to immediately restart all jobs.
• Click a link in the Action column of the batch job row to edit, delete, run, or restart that particular batch job.
• Click the job name to see job properties.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 737
Chapter 12: Advanced setup and administration
Billing and support settings
Starting Rollbase 3.1, the administrator of the Rollbase tenant can access and assign the a billing administrator
and support staff roles from Setup Home>Administration Setup>Billing and Support Settings. The following
describes the responsibilities of the two roles:
• Billing Administrator: A user who can access and upgrade the Rollbase account type, and administer the
invoice history of the Rollbase instance. This role can only be assigned to a Administrative user. By default,
the administrator of the Rollbase tenant is the Billing administrator. For example, only the Billing Administrator
can upgrade Rollbase subscription from Evaluation to Professional.
The Buy Now button at the top-center of a Rollbase instance of users with an Evaluation license and
Upgrade Subscription button in the Subscription Details page is only available to the Billing Administrator.
Additionally, for paid customers, the Invoice History page is only available to the Billing Administrator.
• Support Contacts: Users who are the designated support staff of the Rollbase instance. This option is only
available for paid customers. The users assigned as Support contacts handle the product support related
jobs that include:
• Accessing product knowledge base and product lifecycle related information
• Opening and managing support cases
For Basic and Developer license, you can only add one user as a support contact. For Professional license,
you can add a maximum of five support contacts.
Global text search
This page displays information related to global text search (see Search on page 39):
• Lists objects and their Text Index attribute
• Lists fields with Text Index attribute
• Allows start reindexing for selected object
• Allows start reindexing for all objects
• Allows browsing search-related log file
Monitoring setup
Administrators can monitor runtime status and systems logs for a tenant by navigating to Setup Home >
Monitoring.
The following options are available on the Monitoring page:
• Runtime Status: Links to show status of recently performed system jobs and active user accounts. The
following runtime status monitoring options are available:
• System Jobs: Displays current information about currently running system jobs (such as a spreadsheet
import) running in asynchronous mode.
738 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Support
• Users Online: Displays currently active user sessions, SOAP API sessions, and REST API sessions.
In the Users Online page, you can view user account information, login time, and IP address. You can
also terminate a user/SOAP API/REST API session using the Kill action.
• Portal Users Online: Displays currently active portal user sessions.
• System Logs: Links to show system and access logs. The following logs are available:
• System Events Log: Displays important customer tenant related logs, including information about
application installation and deletion, large data imports, etc.
• System Errors Log: Displays any Java exceptions stored by Rollbase for this customer tenant—except
those caused by formula errors. These records can be viewed for troubleshooting.
Note: Additionally, you can also create reports based on system errors by selecting System Error Log
as the Object Type to report on.
• Users Access Log: Displays user login history.
• Support Access Log: Displays support login history. Whenever a support user logs into your account,
an entry is made in the Support Access Log.
Note: For an administrative user to access your account, you must enable support access (see Enabling
an administrative user to log into a customer tenant on page 683).
• API Logs: Links to SOAP, REST, and JSDO API log files. The following logs are available:
• SOAP API Log: A log that records every SOAP API call.
• REST API Log: A log that records every REST API call.
• Progress Data Service API Log: A log that records every JSDO API call.
Note: You must select the Enable API Log check box from Setup > Administration Setup> Account
Settings to see detailed log records for API calls.
Support
To get product assistance, you can access the following Progress Rollbase support options:
• Help Me option on the Rollbase footer: To read the online Rollbase product documentation.
The online help contains the latest documentation and many useful features such as responsive design,
the ability to translate pages using Google translate (click the globe icon on the toolbar and give it time to
load), the ability to print pages, and search content.
Rollbase also provided PDF help that can be download and used offline. We recommend using the PDF
version only for printing, since the online help contains the latest information and has a better search
capability.
• Rollbase Forum option on the Rollbase menu (see The Rollbase Menu and Help on page 30): To initiate
a product feature discussion and participate in an ongoing discussion in the forum.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 739
Chapter 12: Advanced setup and administration
This option opens the Progress Community page, where you can participate in forums, submit a support
request along with a bug report if applicable. You can also monitor previously posted requests and add
comments to them for further follow up by Progress staff. We generally respond to support tickets within 24
to 48 hours.
• Support option on the Rollbase footer: To open the Progress support page. You can use this page to access
all product support and services. For example, Progress Support Knowledgebase, community, downloads,
and log/update a support request, and education services.
• Subscription Details option on the Rollbase menu (see The Rollbase Menu and Help on page 30): To
view your subscription details. This option opens the About Your Account page in which you can
upgrade/update your account and view the following account details:
• License information
• System information
• System Files
• Latest Progress Rollbase Release
• Your Settings
• Your Rollbase Build Details
Language support
Rollbase supports multiple languages simultaneously in the same tenant and in the same application. This
means that multiple users who speak different languages can use exactly the same application and interact
with it in their own language.
Administrators can optionally select additional languages on the Account Settings page to support multilingual
applications on a tenant. There is one base language, which is the default language for applications on that
tenant, and administrators can add additional languages. The maximum number of additional languages allowed
on a tenant depends on the license agreement. Progress recommends that you do not change the base
language after setting it initially because changing it can have unintended consequences.
On Rollbase Private Cloud, administrators can enable support for languages that Rollbase does not support.
See Adding support for other languages in Private Cloud on page 742 for details.
Administrators can translate applications to any supported language. Translating an application includes loading
translations provided for Rollbase, adding translations for the application's user interface components, and
translating application data. See Translating applications on page 743 for more information.
Rollbase uses the tenant base language for all user accounts by default. Each user can switch to another
supported language by editing their profile on the My Settings page.
Rollbase supports the following languages and provides translations for Rollbase-generated text on setup and
application pages:
• Dutch
• English
• French
• German
• Portuguese
740 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Language support
• Spanish
• Chinese (simplified)
• Japanese
• Korean
• Norwegian
• Russian
• Arabic (Rollbase only provides translations for text on application pages that use the New UI)
• Hebrew (Rollbase only provides translations for text on application pages that use the New UI)
• Greek (Rollbase only provides translations for text on application pages that use the New UI)
When a user selects one of the above languages as their base language, Rollbase-generated text appears in
that language. When a user logs in with the language set to Arabic or Hebrew, the user interface automatically
renders as right-to-left.
Rollbase includes the foundation to support the following languages. You can add the languages to the tenant
and you can provide translations for your applications, but Rollbase does not include any translations for them:
• Turkish
• Italian
The following screen shows a setup screen with the user's language set to French:
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 741
Chapter 12: Advanced setup and administration
The following screen shows an application page with the user's language set to Arabic:
See the following topics for information about translating applications:
• Translating applications on page 743
• Translating application component names and labels on page 746
• Creating and using multilingual string tokens on page 750
• Translating application data on page 752
Adding support for other languages in Private Cloud
In Rollbase Private Cloud, you can add support for new languages by translating the English language resource
file lang_en.properties and saving the translation as a new lang_NN.properties file, where NN
corresponds to the 2-letter ISO 639-1 language code. Language resource files are stored in the directory
<ROLLBASE_HOME>\pas\rollbase\res.
Note: Language resource files are encoded as UTF-8 with BOM. When you edit a language resource file, be
sure to retain this encoding. It is the only supported encoding for this type of file. Some text editors, such as
Notepad++, will display the encoding for the open file.
Each translation is a property name and value in the language resource file. Many property names include one
of the following namespaces:
• newui.eu — Indicates that the translation is only used on application pages (New UI only).
• newui.admin — Indicates that the translation is only used on setup pages and for items on application
pages (New UI only) that are only visible to administrators
You can translate only application page properties, only administrative properties, or all properties. For example,
to translate only end-user visible text on application pages that use the New UI, you only have to provide
translations for properties with the namespace newui.eu. This greatly reduces the amount of effort required
for the translation; you only have to translate about 1000 properties instead of translating over 5000 properties
were you to translate everything.
742 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Language support
The following excerpt from the file lang_fr.properties shows how properties with and without namespaces
appear for the French translation:
newui.eu.AND = AND
newui.eu.And_By = Et par
newui.admin.Animate_Chart = Animer le graphique
newui.admin.Annotation_Type = Type d'annotation
Anonymous = Anonyme
Anonymous_Access = Accès anonyme
For example, to add support for the Vietnamese language:
1. Navigate to the directory <ROLLBASE_HOME>\pas\rollbase\res.
2. Open the file file lang_en.properties and save it as lang_vi.properties file.
3. Edit the properties to provide translations and save the file.
4. Restart your server and open your Rollbase instance.
5. Select Vietnamese from the languages available on the Administration Setup>Account Settings screen.
After you have added support for a language, you can translate applications into that language. See Translating
applications on page 743 for information about translating applications.
Translating applications
You can translate an application if one or more additional languages are assigned in the tenant's Account
Settings. Translations are limited to languages available in the account settings. To translate an application,
you need to translate its component names and labels, such as the application name, object names, and field
labels, as well as the application data input by users. See Translating application data on page 752 for more
information about translating application data. In addition, you can create multilingual string tokens to use in
templates and formulas. This allows any text displayed by the code to appear in the current user's language.
See Creating and using multilingual string tokens on page 750 for more information.
There are two methods for translating application component names and labels:
• Translating them individually on setup pages. Progress recommends using this method when you are
updating an existing, translated application by adding objects, fields, views, or other components. You can
also use this method when creating a new application from scratch, adding translations as you create
components. See Translating individual components for examples. See Translating application component
names and labels on page 746 for a complete list of what you can translate for each component type and
where to translate each.
• Translating all application component names and labels by uploading a spreadsheet containing the
translations. Progress recommends using this method to update an existing application that has not been
translated. This is a good method to use when a third party, such as a translation company, will be providing
the translation. You can also use this method when adding objects to an existing translated application, to
translate the components automatically created during object creation. See Translating component names
and labels using a spreadsheet for details.
Translating individual components
Enter translations for component names and labels when creating or editing them. For example, the following
screen shows translations for a field label.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 743
Chapter 12: Advanced setup and administration
Translate page names, page tab titles, and section titles on the Page Properties screen. Access the Page
Properties screen from the Pages section of an object definition screen. For example, the following screen
shows translations for a page name.
Note that Rollbase renders languages that are written from right to left, such as Arabic in the above screens,
automatically from right to left.
To translate values for picklists, multi-select picklists, radio buttons, and groups of check boxes, you must first
save them in the base language and edit them to specify the field values for additional language fields. See
Picklist, radio button, and group of checkboxes fields for an example.
Translating component names and labels using a spreadsheet
You can translate all component names and labels for an entire application in one spreadsheet. A single
spreadsheet can contain translations for one language. The main steps include downloading a spreadsheet
that lists component names and labels with built-in translations, adding translations to the spreadsheet, and
uploading the fully translated spreadsheet.
The downloaded file contains the Rollbase translations for that language and has the following format:
Column Content
A Original ID of item
B Component's name
C Component's type
D Field's name (inside component)
E Text in base language
F Text in foreign language
Do not modify content of the first five columns as that can render the spreadsheet useless. Only change
translations in the column F using text in column E as a reference. The following screen shows a portion of a
translation spreadsheet with a base language of English and a translation in Spanish:
744 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Language support
Follow these steps to translate an application using a spreadsheet:
1. Navigate to the application's Setup Application screen. (See Editing applications on page 109).
2. From the More Actions menu, click Translation. The Translation screen opens.
3. Select one of the available languages and click Download the current translation as XLS spreadsheet.
4. Update the spreadsheet as described above, adding translations to column F.
5. Save the XLS file to your local disk.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 745
Chapter 12: Advanced setup and administration
6. Navigate to the Translation screen, verify that the correct language is selected, and upload the XLS file.
Rollbase reads the file once to translate application components and keeps the file as an application resource.
7. If you later modify the translations in the XLS file, follow steps 4 through 6 using the updated file. You can
then re-publish the application or serialize it to XML.
The following screen shows an application that has been translated to Spanish. Note that existing application
data has not yet been translated in this example. See Translating application data on page 752 for information
about translating data.
Translating application component names and labels
You can translate individual application component names and labels for an existing application or you can
translate component names and labels when creating them. The following table contains the types of application
components, what you can translate for each component, and where to translate each type of component.
746 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Language support
Table 5: Translating application components
Component What you can translate Where to translate
Application Application Name, Description New Application screen or Edit Application
screen. See Creating and managing applications
on page 108. Note that the Quick Create wizard
does not provide fields for translating new
components.
Tab Tab Name, Description New Tab screen or Edit Tab screen. See Creating
tabs and pages on page 362.
Portal Portal Name, Description New Portal screen or Edit Portal screen. See
Creating a portal on page 526.
Role Role Name, Description New Role screen or Edit Role screen. See
Creating and editing user roles on page 650.
Hosted File File Name, Description New Hosted File screen or Edit Hosted File
screen. See Managing hosted files on page 547.
Batch Job Job Name New Batch Job screen, Edit Batch Job screen.
See Batch jobs on page 736.
Catalog Description New Progress Data Catalog screen, Edit
Progress Data Catalog screen. See Creating
Progress Data Catalogs for external applications
on page 640.
Object Singular Name, Plural Name, New Object screen, Edit Object screen. See
Record Name, Description Creating and managing objects, fields, and
relationships on page 128. When you create a new
object definition, Rollbase automatically creates
pages, views, and fields for that object. These
components should also be translated.
Field Field Label, View Header, New Field screen, Edit Field screen. See Creating
Field-Level Help , Values (for and managing objects, fields, and relationships on
picklists, multi-select picklists, page 128. To translate values for picklists,
radio buttons, and groups of multi-select picklists, radio buttons, and groups of
check boxes only) check boxes, you must first save them in the base
language and edit them to specify the field values
for additional language fields. See Picklist, radio
button, and group of checkboxes fields for an
example.
Relationship Singular Name and Plural New Relationship screen, Edit Relationship
Name for each side of the screen. See Creating and managing objects, fields,
relationship and relationships on page 128.
Page Tab Name, Section Title Properties screen for the page, page editor. See
Pages, the page editor, and grid controls on page
362.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 747
Chapter 12: Advanced setup and administration
Component What you can translate Where to translate
HTML component on Language Page editor. See HTML component on a page for
page more information.
View View Name New View screen, Edit View screen. See Creating
and editing views on page 437.
Template Template Name, Subject (email New Template screen, Edit Template screen.
template only) See Working with templates on page 184.
Chart Chart Name, X Axis Label, Y New Chart screen, Edit Chart screen. See
Azis Label Working with charts on page 343.
Report Report Name, Description New Report screen, Edit Report screen. See
Working with reports on page 299.
Gauge Gauge Title New Gauge screen, Edit Gauge screen. See
Working with gauges on page 347.
Trigger Trigger Name New Trigger screen, Edit Trigger screen. See
Trigger overview on page 218.
Workflow Process Process Name New Workflow Process screen, Edit Workflow
Process screen. See Workflow processes on page
255.
Workflow Status Status Name New Workflow Status screen, Edit Workflow
Status screen. See Workflow status on page 264.
Workflow Action Action Name New Workflow Action screen, Edit Workflow
Action screen. See Workflow actions on page 266.
Button Display Label New Button screen, Edit Button screen. See
Using buttons on pages on page 393.
Conversion Map / Map Name New map screen, Edit map screen. See Converting
Import Map records on page 160 and Importing data on page
622.
Picklist, radio button, and group of checkboxes fields
To translate values for picklists, multi-select picklists, radio buttons, and groups of check boxes, you must first
save them in the base language and edit them to specify the field values for additional language fields.
Note: The additional language fields do not appear unless the field definition has been saved. Do not change
or override base language fields (which are included by default).
For example, suppose you support two languages in your tenant, English (base language) and Portuguese
(additional language). If you have a picklist item, Autumn, in the base language field and in Portuguese, you
want it to appear as Outono, specify the following in the Portuguese language field:
Autumn: Outono
748 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Language support
HTML component on a page
You can create content in multiple languages in the same HTML component. If multiple languages are enabled,
the component contains a drop-down list from which you can select a language.
The screen below shows an HTML component with English selected:
After selecting a language, create HTML content in that language.
The screen below shows the same HTML component with Spanish selected:
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 749
Chapter 12: Advanced setup and administration
While you could use a multi-lingual string token to accomplish the same results, this method is better when the
text only appears in one place in the application. If you want to use the same text in multiple languages in
several places in the application, you can use string tokens. See Creating and using multilingual string tokens
on page 750 for more information.
Creating and using multilingual string tokens
String tokens in Rollbase can support multiple languages. You can use multilingual string tokens to localize
display text generated by your code. See Creating and using string tokens on page 193 for more information
about string tokens.
Every string token you create is available to any application in the tenant. You must attach a string token to
any application that uses it before publishing or exporting the application. See Attaching string tokens for details.
Suppose a tenant is configured to support three languages: English (base language), German (additional
language) and French (additional language). The following example shows how a multilingual string token
works in an HTML component on a page.
When you create a string token, the New String Token dialog contains a field for each language supported
by the tenant. Enter the string token value for each supported language and a Token Name. The following
screen shows an example string token that evaluates to a welcome message for the Lending Library application:
750 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Language support
The following screen shows an HTML component that uses the string token:
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 751
Chapter 12: Advanced setup and administration
Rollbase will render the above HTML component based on the user's language setting. The screens below
show the resulting text when the user's language is set to English and when the user's language is set to
German:
Translating application data
When multiple languages are enabled for a tenant, and fields have been enabled to support multiple languages,
end users will be able to enter field values in multiple languages. You can enable fields to support multiple
languages even if the application's component names and labels have not been translated.
Rollbase supports values for Text, Text Area, and Record Name fields in the base language and in additional
languages. The first entry is always in the base language of the tenant. When users create or edit records,
they will see fields to enter values for the base language and for each additional language supported by the
tenant. Rollbase automatically renders fields for languages that are written from right to left, such as Arabic or
Hebrew, from right to left.
752 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Enabling Google Apps for Rollbase Private Cloud
The screen below shows a field with values in English, Arabic, and Spanish:
Users can mix left-to-right and right-to-left languages in the same field, and Rollbase will render each in the
correct direction. The screen below shows the Arabic field with English text added:
When viewing a record (either on a View page or where the record is in a list of records), the field value is
displayed in the user's selected language. For example, the screen below displays the Spanish value for the
Title field:
To enable users to enter data in multiple languages, select the This field allows storing multiple values for
supported languages check box when creating or editing a field. You must select this check box for each
field that you want to support values in multiple languages.
Enabling Google Apps for Rollbase Private Cloud
To enable the use of Google Apps in Rollbase Private Cloud, you must set up Google OAuth 2.0 for your
Rollbase Private Cloud instance. The procedure includes acquiring a Google Client ID and a Google Client
Secret Key from a Google project and then updating the GoogleClientId and GoogleClientSecretKey
properties in the Shared Properties for Rollbase Private Cloud.
To enable the use of Google Apps in Rollbase Private Cloud, do the following:
Note: Only the users with access to Shared Properties for Rollbase Private Cloud instance can enable
the use of Google Apps.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 753
Chapter 12: Advanced setup and administration
1. Create a new Project in Google Developers Console for Rollbase. For information on creating a project,
see https://developers.google.com/console/help/new/#creatingdeletingprojects.
2. Activate Calendar API, Drive API, Google+ API, and Gmail API in your Project. These APIs must be included
in your project if you want to use Gmail and sync Google Calendar in Rollbase. For information on activating
APIs, see https://developers.google.com/console/help/new/#activatingapis.
3. Set up OAuth 2.0 and create a new Client ID for Rollbase Private Cloud. For information on setting up OAuth
2.0, see https://developers.google.com/console/help/new/#generatingoauth2.
In the Create Client ID dialog, you must provide the following values:
1. Select Web application as your APPLICATION TYPE.
2. If prompted with the Consent Screen, provide the appropriate account details in the consent screen
and click Save. The Create Client ID page reappears.
3. In the AUTHORIZED JAVASCRIPT ORIGINS field, specify the javascript origin of the Rollbase Private
Cloud URL, http://<computer-name>:<port-number>/.
For example, if your Rollbase Private Cloud URL is
http://localhost:8830/router/login/loginPrivate.jsp, then you must specify and authorize
http://localhost:8830/ as your javascript origin.
4. In the AUTHORIZED REDIRECT URIS field, specify all the Rollbase server URLs in the format:
http://<computer-name>:<port-number>/<server-name>/router/servlet/oauth2callback.
For example, if your Rollbase Private Cloud URL is
http://localhost:8830/router/login/loginPrivate.jsp, then you must specify and authorize
http://localhost:8830/router/servlet/oauth2callback your redirect URI.
5. Click Create Client ID.
Client ID for the Web application appears.
4. Copy the CLIENT ID and CLIENT SECRET values, and paste them as values for GoogleClientId and
GoogleClientSecretKey properties in your Rollbase Private Cloud's Shared Properties.
5. Log into Rollbase Private Cloud as Master Admin.
6. Navigate to System Console > System > Control Panel > Configuration > Google Integration and
configure your Google Apps account for Rollbase. For more information about Google Apps Settings, see
Control Panel on page 814.
Note: After the Rollbase Private Cloud's Shared Properties is updated with the aforementioned
properties, all the users in the Rollbase tenant will be able to configure their Google accounts and use
Google Apps in Rollbase.
754 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
13
Installing and administering Private Cloud
The topics in this section describe how to install, configure, and administer Rollbase Private Cloud.
For details, see the following topics:
• Introduction
• Installation
• Administration
• Private Cloud security and access control
• Multi-server environments
• CDN Support
• Configuration file reference
• PAS command line reference
Introduction
® ®
Progress Rollbase Private Cloud is a fully functional version of the Rollbase platform that you can download,
install and host on your own servers or on another cloud platform. A Private Cloud system includes all of the
design and runtime functionality of hosted Rollbase. Rollbase Private Cloud supports single server and
multi-server deployments, as defined by your license, see
http://www.progress.com/products/rollbase/pricing/rollbase-private-cloud for pricing details.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 755
Chapter 13: Installing and administering Private Cloud
Private cloud end-users can be individuals or departments within your organization or others to whom you sell
Rollbase applications and services. You can create separate tenants to keep sets of applications separate and
secure for different groups of users. Each customer tenant will have its own login account.
Evaluating Rollbase
You can evaluate Rollbase Private Cloud as long as you want at no cost. You simply register, download and
install the software with no license. Without a license, Rollbase enforces the following limitations:
• Every page displays the notification, Free Rollbase Evaluation.
• A maximum of one database instance (MySQL, OpenEdge, DataDirect Cloud, MS SQL Server, or Oracle)
and one Rollbase instance
• A maximum of two Customers tenants, with two User accounts and 5000 object records (total for all objects)
in each tenant.
• Progress Technical Support only provides answers to installation-related questions. However, you can join
Progress Community Rollbase Technical Users forums, which provide answers to a variety of questions.
Runtime Architecture
Rollbase Private Cloud requires the following runtime components:
• One or more Java Web application server instances to which Rollbase components are deployed (The
®
installer includes the Progress Application Server (PAS)). PAS is based on Apache Tomcat but is tailored
to be secure for use in production systems. PAS also simplifies the process required to create and run
multiple Rollbase components on different hosts. Each PAS shares the executables and libraries of a
common Tomcat server, but each instance is a separate process, running in a separate JVM, with its own
configuration, such as for ports, security framework, and Web applications.
• One or more database instances. The database can be on its own host or be collocated with Rollbase
components. The following image illustrates a single server Rollbase Private Cloud architecture with Rollbase
auxiliary components identified in the call-out.
If you choose not to use PAS, you will need to install and configure your Web server to work optimally with
Rollbase. Since Progress certifies use of Apache Tomcat with Rollbase, the documentation provides PAS and
Tomcat-specific information. If you are using another Web server, refer to that documentation to find the
equivalent functionality.
756 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Introduction
The multi-server architecture supports multiple instances of all components, which can be distributed for
performance and scalability. See Planning your multi-server architecture on page 869
The first Rollbase instance you install is a Master Server, from which you can:
• Create and manage customers (tenants).
• Monitor system components.
• Setup ISV partners.
• Manage a shared applications directory and a support portal.
• Run applications for your own business, such as CRM, bug tracking, and customer support.
See Administration for more information.
Progress offers the following installation package options:
®
• The Rollbase Private Cloud installer for Microsoft Windows and Linux operating systems. In addition to
Rollbase, you can optionally install an OpenEdge database, and the Pacific App Server, a pre-configured
instance of Tomcat. See Using the Rollbase installer on page 761.
• Zipped packages allow advanced users to install Rollbase components manually. This method of installation
works best for multi-server environments or for operating systems not supported by the Private Cloud
Installer. See Setting up Rollbase manually on page 768.
Platforms supported for Private Cloud
Progress Software certifies particular versions of browsers, operating systems, databases, and web servers
to work with Private Cloud. Other versions might work with no problems, but are not certified. See Supported
Platforms for this information for the latest release.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 757
Chapter 13: Installing and administering Private Cloud
Licensing
Under the terms of the Rollbase license you cannot reverse-engineer or modify the Rollbase software. You
can, however, customize the appearance of your web pages by replacing standard Rollbase resource files
(images, icons and CSS) with your own files.
Each Progress Rollbase Private Cloud license is associated with a particular domain name, such as
www.mycompany.com. You must purchase a new license to use a different domain name. Each Private Cloud
license has an expiration date, after which Rollbase will no longer run. The expiration date includes a window
of time to renew the license.
You can delete the license file to switch to the free evaluation edition. However, if you have more than two
tenants, you will get a license error because a free evaluation only allows two tenants.
See Private Cloud pricing options For enterprise and ISV pricing or to purchase, see the contact information
on our website.
OpenEdge license restrictions
If you install the OpenEdge database that is packaged with the installer, that instance of OpenEdge can only
be used as the embedded database for the Rollbase application and the standard Rollbase tables. Specifically,
the following restrictions apply:
• The database cannot be used for OpenEdge (PUB schema) ABL-accessible tables.
• You cannot add SQL tables to this database.
Private Cloud updates
Progress periodically provides Private Cloud software updates for download. To check on updates, go to this
page:Rollbase Private Cloud Downloads Portal, and log in using your Private Cloud download account, which
is separate from your Progress ID. Some updates require you to also run update scripts on your database(s).
If you customize the look and feel of application web pages, updates might replace your resource files with
Rollbase resources. It is your responsibility to maintain your resource customizations.
Included Rollbase applications
The applications listed in the following table are installed in the Web Server deployment directory. For example,
for PAS, in the webapps folder. If you distribute applications, make sure to include the required applications
called out in the table.
Application Name Description Notes
Rollbase The main Rollbase system Must be installed in every customer
application that defines the USER tenant at creation time. See
object to manage user accounts and Managing Customers and Users for
will be installed by default for each more information
customer tenant.
Organization Management Defines Location, Department, Recommended for installation in
Function and Group objects. every tenant at creation time.
758 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Introduction
Application Name Description Notes
System Console Used to monitor and manage all To be installed in the Master Server
Rollbase components, such as the only.
creation of a new Customer, and
includes the Marketplace portal.
ISV Partner Gives your ISV partners limited To be installed in the Master Server
access to your Master Sever. only.
Support Center Includes a Support Portal to To be installed in the Master Server
facilitate submission and processing only.
of support requests from your users.
Approvals Defines a default approval process Recommended for installation in
(can be sequential or parallel). every Tenant.
CRM Simple CRM application that can be Can be installed as desired from
further customized and used as a your Marketplace portal.
starting point.
Third party software you can install
The software described in this section is used by Rollbase Public Cloud. To use it with Rollbase Private Cloud,
you must download and install it separately, and purchase any required licenses.
Aspose.Words for Java
Note: Starting with Rollbase 4.2, Rollbase Private Cloud includes a beta quality open source library-based
implementation.
Rollbase uses Aspose.Words for Java to process Word-based document templates.
To use Aspose.Words for Java with Rollbase Private Cloud, do the following:
1. Download and purchase Aspose.Words for Java 14.8.0 from:
http://www.aspose.com/community/files/72/java-components/aspose.words-for-java/default.aspx.
2. Optionally, if you have a previous version of Aspose.Words for Java, you must remove the related .jar
and .lic files from your Rollbase installation.
3. Copy aspose-words-14.8.0-jdk16.jar into the Web server lib directory.
For example, if you used the installer, installed PAS, and accepted the default folder, this location would
be Progress\Rollbase\Pas_Instance\common\lib.
4. Copy the Aspose.Words.lic license file into the config directory of your Rollbase installation.
For example, if you used the installer, installed PAS, and accepted the default folder, this location would
be Progress\Rollbase\Pas_Instance\rollbase\config.
5. Restart PAS or Tomcat.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 759
Chapter 13: Installing and administering Private Cloud
Aspose.Pdf for Java
Note: Starting with Rollbase 4.2, Rollbase Private Cloud includes a beta quality open source library-based
implementation.
Rollbase uses Aspose.Pdf for Java to process PDF writable forms and to extract plain text from PDF documents
for search indexing.
To use Aspose.PDF for Java with Rollbase Private Cloud, do the following:
1. Download and purchase the Aspose.Pdf for Java 9.3.1 from:
http://www.aspose.com/community/files/72/java-components/aspose.pdf-for-java/default.aspx.
2. Optionally, if you have a previous version of Aspose.Pdf for Java, you must remove the related .jar and
.lic files from the Rollbase directory.
3. Copy aspose-pdf-9.3.1-jdk16.jar into the Web server lib directory.
For example, if you used the installer, installed PAS, and accepted the default folder, this location would
be Progress\Rollbase\Pas_Instance\common\lib.
4. Copy the Aspose.Pdf.lic license file into the config directory of your Rollbase installation.
For example, if you used the installer, installed PAS, and accepted the default folder, this location would
be Progress\Rollbase\Pas_Instance\rollbase\config.
5. Restart PAS or Tomcat.
Installation
Where and how you install Rollbase depends on the architecture you have selected, whether you are require
a single server or multi-server architecture, and which database(s) you plan to use. There are two ways to set
up Rollbase:
• Use the Rollbase Private Cloud installer (for Windows or Linux operating systems)
The installer gives you the option to install a Progress OpenEdge Database and PAS, a pre-configured
version of Tomcat. If you don't use these, you must install a Web server and a database separately and
configure them to work with Rollbase. The OpenEdge and PAS instances installed by the Rollbase installer
are not set up as Windows services. To configure the installed PAS instance as a windows service or Linux
daemon, see Installing and running an instance as a Windows service on page 873 or Installing and running
a PAS instance as a Linux daemon on page 874.
You can use the installer in one of three modes:
• Default mode — A mode that uses a series of dialogs to guide you through the installation.
• Console mode — A mode that uses text-only prompts to guide you through the installation.
• Silent mode — A mode that enables the installer to run without any user interaction.
• Install Rollbase manually by extracting zip files
The zip files provide flexibility for multi-server configurations and on operating systems on which the installer
will not run. Manual installation with the zip files requires you to configure a web server and database
separately and edit Rollbase configuration files.
760 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Installation
The first Rollbase instance you install and configure becomes the Master Sever. To use multiple Rollbase
instances or auxiliary components, see Multi-server Edition. In a multi-server configuration, you will log in to
the Master Server for administering your Private Cloud deployment.
Note: Default installations of third party software often are configured to use minimum security. Please review
vendor websites and documentation for recommended security configuration, such as changing default
administrator passwords.
Prerequisites
Before you can download and install Rollbase Private Cloud:
• You will need a Rollbase Private Cloud download account.
• All hosts on which you plan to install Rollbase must have Java installed. The Private Cloud installer will
install a JRE for you. If you are doing a manual install, download and install the latest version of the Oracle
Java 8 runtime environment from www.oracle.com.
• If you are going to use Rollbase with an existing Web server, make sure that the Web server is stopped
and not restarted until you finish the entire installation process.
If you've installed Tomcat as a Windows service, run tomcat<version>.exe to stop the service (or
navigate to the Services panel to stop it manually).
• You need a database and a compatible JDBC driver. The Rollbase Private Cloud installer allows you to
install Progress OpenEdge, which includes a JDBC driver. To use a different database, that database must
be configured with an account that Rollbase can access. The account should have all permissions. Configuring
a supported database on page 772 describes the scripts Rollbase provides to create the necessary tables.
• On Windows, you need to run all installation and startup scripts as an administrator. On Linux, you to run
all installation and startup scripts as root.
The following topics describe the detailed installation procedures:
• Using the Rollbase Private Cloud Installer
• Installing Rollbase Manually from Zip Files
Using the Rollbase installer
If you will use Rollbase with an existing Web server, stop it before installing Rollbase.
Note: If you are upgrading from a release prior to 5.0, please read Upgrading Private Cloud to Version 5.x on
page 70 before running the installer.
To use the Rollbase Private Cloud installer, follow these steps:
1. From the Rollbase Private Cloud Downloads Portal, download the zip file for your operating system:
• For Windows, PROGRESS_ROLLBASE_FULL_INSTALLER_<version_number>_WIN_64.zip.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 761
Chapter 13: Installing and administering Private Cloud
• For Linux, PROGRESS_ROLLBASE_FULL_INSTALLER_<version_number>_LINUX_64.zip.
2. Unzip the downloaded file.
The resulting files include an installer executable and a zip file for the OpenEdge database.
3. Run the installer in one of the following modes:
• Default mode, which uses a series of dialogs to guide you through the installation. See Installing Rollbase
using the default mode on page 762 for details.
• Console mode, which uses text-only prompts to guide you through the installation. See Installing Rollbase
using console mode on page 764 for details.
• Silent mode, which enables the installer to run without any user interaction. See Installing Rollbase using
silent mode on page 765 for details.
If you use a Gmail server, you must set up Google OAuth 2.0 for your Rollbase Private Cloud instance. The
procedure includes acquiring a Google Client ID and a Google Client Secret Key from a Google project.
See steps 1-4 of Enabling Google Apps for Rollbase Private Cloud on page 753 to generate the required ID
and Key.
The Welcome email is not sent to the first admin and an exception is thrown in the log and the console.
This exception is expected as it still requires the user to authenticate with a browser the first time.
Refer solution mentioned here:
https://stackoverflow.com/questions/10835365/authenticate-programmatically-to-google-with-oauth2
After installing Rollbase private cloud, proceed to Postrequisites on page 767.
Installing Rollbase using the default mode
To run the installer using the default mode:
1. Run the installer executable and click Next to start the installation process.
2. Accept the Progress Rollbase License agreement and click Next.
3. Optionally, specify the location of your license file.
Without a license, Rollbase will run in evaluation mode. You can add a license at any time.
4. Click Next.
5. Specify a destination directory for the installation and a working directory for the OpenEdge database. If
you are using a different database, the working directory is not important.
Note: Do not use paths that contain spaces, such as Program Files.
6. Click Next.
7. Choose the database type you want to use for Rollbase.
• Progress Database — Allows you to use an existing Progress OpenEdge Database or have the installer
install one.
• Other Database — Select this to use one of the supported databases. You will need to configure it
yourself, as described in Configuring a supported database on page 772.
8. Click Next
762 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Installation
9. For Server Details, enter the host name and port number for Rollbase. If you have a license, the host name
should match that in your license. If you elected to use an OpenEdge database, for Database Details, enter
details for an existing OpenEdge database or for a new one. If you want the installer to create the database,
check the box.
10. Click Next.
11. Choose the option to install the Progress Application Server (PAS) or to use an existing Tomcat installation.
If the latter, make sure the Tomcat instance is a supported version and is not running.
12. Click Next.
13. If you chose to install PAS, specify port numbers. You only need to change the port numbers if they conflict
with ports already in use on your network.
14. Specify Mail Server Details. Rollbase will use this mail server to send emails. It can be an organizational
mail server or email service such as Google (smtp.gmail.com, port 465) or Yahoo
(stmp.mail.yahoo.com, port 465). Values must be entered but can be changed later in the Shared
Properties or in administrative setup. The Shared Properties on page 786 will contain the values you
enter here.
• Host Name — Host name of the desired email server
• Port Number — Desired email server port number
Note:
If you use a Gmail server, you must set up Google OAuth 2.0 for your Rollbase Private Cloud instance. The
procedure includes acquiring a Google Client ID and a Google Client Secret Key from a Google project.
See steps 1-4 of Enabling Google Apps for Rollbase Private Cloud on page 753 to generate the required ID
and Key.
The Welcome email is not sent to the first admin and an exception is thrown in the log and the console.
This exception is expected as it still requires the user to authenticate with a browser the first time.
Refer solution mentioned here:
https://stackoverflow.com/questions/10835365/authenticate-programmatically-to-google-with-oauth2
15. Specify the Administrator Details email. This email address will identify the first administrative user on the
system and must be a valid email address. This would typically be your e-mail address unless someone
else will be administering Rollbase.
16. Specify Email Account information. Rollbase will send system emails from this account. Values must be
entered but can be changed later in the Shared Properties. For example, you might want to set up an
account named something like [email protected]. The Shared Properties on page 786 file will contain
the values you enter here.
• User Name — Email server user name used to send system messages
• Password — Email account password
17. Click Next.
18. Review the Pre-Installation Summary. If acceptable, click Next.
The installation process starts.
19. Click Done when complete.
After installing Rollbase Private Cloud, proceed to Postrequisites on page 767.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 763
Chapter 13: Installing and administering Private Cloud
Installing Rollbase using console mode
To run the installer in console mode:
1. Open a command prompt in the directory that contains the installation executable.
2. Run the following command:
cmd > ROLLBASE_FULL_INSTALLER_<version>_WIN_64.exe -i console
3. Follow the prompts as directed. See Installing Rollbase using the default mode on page 762 for a description
of the information you need to enter.
Note:
If you use a Gmail server, you must set up Google OAuth 2.0 for your Rollbase Private Cloud instance. The
procedure includes acquiring a Google Client ID and a Google Client Secret Key from a Google project.
See steps 1-4 of Enabling Google Apps for Rollbase Private Cloud on page 753 to generate the required ID
and Key.
The Welcome email is not sent to the first admin and an exception is thrown in the log and the console.
This exception is expected as it still requires the user to authenticate with a browser the first time.
Refer solution mentioned here:
https://stackoverflow.com/questions/10835365/authenticate-programmatically-to-google-with-oauth2
4. If you did not choose to install PAS, verify that your Tomcat installation is configured as described in Using
your own instance of Tomcat on page 767, including:
• Disable system persistence
• Ensure proper UTF-8 support
• Specify <session-timeout> node value
5. If you are using a new Tomcat instance that you installed yourself, set JRE_HOME as described in Set
Environment Variables. Note that the installer will have already set ROLLBASE_HOME.
After installing Rollbase Private Cloud, proceed to Postrequisites on page 767.
764 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Installation
Installing Rollbase using silent mode
To run the installer in silent mode:
1. Create a properties file (named response.properties in the example below) containing the values you
want to use during the installation. See Example response.properties file on page 766 for an example.
2. Open a command prompt in the directory that contains the installation executable.
3. Run the following command:
cmd > ROLLBASE_FULL_INSTALLER_<version>_WIN_64.exe -f response.properties -i silent
Note:
If you use a Gmail server, you must set up Google OAuth 2.0 for your Rollbase Private Cloud instance. The
procedure includes acquiring a Google Client ID and a Google Client Secret Key from a Google project.
See steps 1-4 of Enabling Google Apps for Rollbase Private Cloud on page 753 to generate the required ID
and Key.
The Welcome email is not sent to the first admin and an exception is thrown in the log and the console.
This exception is expected as it still requires the user to authenticate with a browser the first time.
Refer solution mentioned here:
https://stackoverflow.com/questions/10835365/authenticate-programmatically-to-google-with-oauth2
4. If you did not choose to install PAS, verify that your Tomcat installation is configured as described in Using
your own instance of Tomcat on page 767, including:
• Disable system persistence
• Ensure proper UTF-8 support
• Specify <session-timeout> node value
5. If you are using a new Tomcat instance that you installed yourself, set JRE_HOME as described in Set
Environment Variables. Note that the installer will have already set ROLLBASE_HOME.
After installing Rollbase Private Cloud, proceed to Postrequisites on page 767.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 765
Chapter 13: Installing and administering Private Cloud
Example response.properties file
The following is example content for a response.properties file passed to the Rollbase installer in silent
mode:
#Progress Rollbase License File
#------------------------------
PATH_ROLLBASE_LICENSE=
#Destination and Working Directories
#-----------------------------------
USER_INSTALL_DIR=C:\\Progress\\Rollbase
USER_WORK_DIR=C:\\Progress\\WRK
#Database Type
#-------------
USE_PROGRESS_DB=1
USE_NON_OE_DB=0
#Database
#--------
DB_HOST_NAME=localhost
DB_PORT_NUMBER=8911
DB_USER_NAME=dbadmin
DB_PASSWORD=dbadmin
DB_NAME=rbdb
DB_LOCATION=C:\\Progress\\WRK\\oe_rollbase_db
#Application Server
#------------------
USE_NEW_TOMCAT=1
USE_EXISTNG_TOMCAT=0
TOMCAT_DIR=C:\\Progress\\Rollbase\\pas
#PAS Instance Port Numbers
#-------------------------
HTTP_PORT=8830
HTTPS_PORT=8831
SHUTDOWN_PORT=8832
#Choose EMail Server
#-------------------
USER_EMAIL_SMTP=1
USER_EMAIL_MSEX=0
USER_EMAIL_GMAIL=0
#Email Configuration
#-------------------
MAIL_HOST_NAME=Localhost
MAIL_PORT_NUMBER=1234
[email protected]
MAIL_USER_NAME=testUser
MAIL_PASSWORD=Passsword
MAIL_USE_NONE=1
MAIL_USE_SSL=0
MAIL_USE_TSL=0
Note: In the above example, the Email Configuration is done for SMTP server. However, when you configure
email for Exchange server or Gmail server, the email content in the response.properties file is as follows.
Exchange server properties:
#Choose EMail Server
#-------------------
USER_EMAIL_SMTP=0
USER_EMAIL_MSEX=1
USER_EMAIL_GMAIL=0
#Microsoft Exchange Server Configuration
#---------------------------------------
[email protected]
[email protected]
MAIL_PASSWORD=Password
766 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Installation
Gmail server properties:
#Choose EMail Server
#-------------------
USER_EMAIL_SMTP=0
USER_EMAIL_MSEX=0
USER_EMAIL_GMAIL=1
#GMail Configuration
#-------------------
[email protected]
[email protected]
GOOGLE_REFRESH_TOKEN=<any value>
GOOGLE_CLIENT_ID=Google client ID
GOOGLE_CLIENT_SECRET_KEY=Google secret key
Postrequisites
After installing Rollbase Private Cloud:
• If you are using a database other than OpenEdge, you need to run the scripts for that database and enter
information about it in the node-config.json file. Then, you can start the runtime components as described
in Starting components and logging In on page 777.
• The default Web server configuration may not completely secure your Web server. For example, depending
on your environment, unauthorized users could access your data on the servers. Progress recommends
that you optimally secure your Web servers by conforming to the benchmarks given by Center for Internet
Security (CIS). For information on CIS security benchmarks, see
http://benchmarks.cisecurity.org/downloads/browse/?category=benchmarks.servers.web.
Using your own instance of Tomcat
If you are using your own Tomcat instance instead of PAS, Progress recommends the following:
• Use an instance of Tomcat dedicated to Rollbase. Download a version of Tomcat that Progress certifies.
Note:
If you are using Tomcat 8 or higher, you must prevent Tomcat from scanning the Rollbase JAR file by adding
the following line to the context.xml file in the conf folder of the Tomcat installation:
<JarScanner scanClassPath="false" scanAllFiles="false" scanAllDirectories="false"/>
• Start by using the default port 8080 for Tomcat. Later you can add Apache as a gateway to your Tomcat
instance (Apache typically runs on port 80).
• Follow Apache's installation instructions. Once installed, start Tomcat and point your browser to
http://localhost:8080 to make sure that you see the Tomcat welcome page. Stop Tomcat once confirmed.
• Run Tomcat from the command line during installation. To do this open a command prompt window and
go to the bin directory within your Tomcat folder and run tomcatX.exe (where X is the main version number
of your Tomcat installation).
• The default Tomcat installation is optimal for development purposes. For deployment, you will likely want
to increase security. See the Tomcat documentation for details.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 767
Chapter 13: Installing and administering Private Cloud
• Set Tomcat up to use as much memory as you can spare for its initial and maximum memory pools: for
example, 1500MB in production on a 32-bit machine (you can more than double this for a 64-bit OS).
However, f you set memory requirements too high Tomcat will fail to start.
• Disable session persistence: un-comment the section of conf/context.xml related to session persistence.
• For proper UTF-8 support, add server.xml include a URIEncoding attribute with value of UTF-8 to all
Connector nodes:
<Connector port="8009" protocol="AJP/1.3" redirectPort="8443" URIEncoding="UTF-8"/>
• To ensure that portal user log in sessions last long enough, update the <session-timeout> node value in
the web.xml configuration file in the conf directory. The default timeout is 30 minutes. The appropriate
value depends on your application and end-users usage patterns.
• After you have verified that the settings work well, you can set up the Tomcat instance as a Windows Service
or Linux Daemon. See your Tomcat documentation.
• Periodically delete files from Tomcat's log directory.
Setting up Rollbase manually
The topics in this section explain how to manually install and configure Rollbase Private Cloud on a single
server, such as: a dedicated in-house server, a third party server, a cloud infrastructure such as Amazon or
Rackspace, or a laptop for testing. To use multiple Rollbase instances or auxiliary components, see Multi-server
Environments.
If the host on which you want to install Rollbase Private Cloud has a Windows or Linux operating system, using
the installer instead of installing manually allows you to avoid a number of manual configuration tasks.
The high-level steps required to install manually include the following:
1. Verify that Tomcat and the database you plan to use with Rollbase Private cloud are installed and configured
as described in Using your own instance of Tomcat on page 767.
2. Verify that Tomcat is stopped and not restarted until you finish all necessary steps for installing and configuring
Rollbase. If you've installed Tomcat as a Windows service, run tomcat8w.exe to stop the service (or
navigate to services to stop it manually). For Ubuntu Linux platform, run the shutdown.sh script.
3. Download and unzip Rollbase components.
4. Set environment variables.
5. Edit the node-config.json file
6. Run the Rollbase script for your database type.
7. Start the runtime components and log into Rollbase.
Download and unzip Rollbase components
The following steps assume that you have a Rollbase Private Cloud download account and that you have a
Web server installed, such as Apache Tomcat. Make sure that the Web server is stopped while you follow the
steps below.
Follow these steps to download and unzip Rollbase:
1. From the Rollbase Private Cloud Downloads Portal, download the following files to your server:
• rollbase.zip: Configuration and resource files
768 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Installation
• lib.zip: Shared libraries
• webapps.zip: Web archives for Rollbase and auxiliary components
2. Create a directory to hold the Rollbase files, such as \Progress.
The person who will start Rollbase must have permissions to write to this directory.
3. Preserving the folder structure, unzip rollbase.zip into the directory you created.
You should see a rollbase directory with the following sub-directories:
• apps: contains XML files for applications to be installed
• config: contains configuration files
• res: contains localized resource strings
• docs: contains documentation
• sql: contains SQL script needed to create Rollbase database
4. Unzip webpps.zip into your web server deployment folder. For Tomcat, the webapps folder in its installation
directory.
5. Unzip lib.zip in the web server library directory. For Tomcat, the lib folder in the Tomcat installation
directory.
Next, you will need to set environment variables.
Set environment variables
The ROLLBASE_HOME environment variable should point at your Rollbase installation, the directory containing
Rollbase config and res folders. The JRE_HOME variable should point at the jre folder of your Java
installation. If you used the Rollbase installer, it creates and sets these variables for you. This topic describes
how to set these variables on hosts with Windows and Linux operating systems.
On Windows Machines
To set the ROLLBASE_HOME environment variable on a host with a Windows OS:
1. In Windows Explorer, right-click Computer or My Computer and select Properties.
2. Click Advanced System Settings.
3. Click Environment Variables.
4. Under the list of System variables, click New
5. Enter ROLLBASE_HOME for the Variable name and the full path to the root directory of your Rollbase
installation for the Variable value. For example, if you unzipped rollbase.zip in a C:\Progress
directory, the path would be C:\Progress\rollbase.
6. Click OK.
7. Under the list of System variables, click New
8. Enter JRE_HOME for the Variable name and the path to the jre directory of your Java installation for
Variable value. For example, if the Java installation is in C:\Java, the path would be
C:\Java\jre<version>.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 769
Chapter 13: Installing and administering Private Cloud
On Linux Machines
On Linux or UNIX based machines use the commands ROLLBASE_HOME= and JRE_HOME=. For example,
using the bash shell and assuming a location of usr/share/rollbase, the command would be as follows:
export ROLLBASE_HOME=/usr/share/rollbase
Editing the node-config.json file
Ensure that you have set the environment variables.
Edit the node-config.json file content as described below.
1. Wherever it is present in the node-config.json file, replace $HTTP_PORT$ with 8080 or server configured
port.
2. Wherever it is present in the node-config.json file, replace $HTTPS_PORT$ with 443 or server configured
port.
3. Update the following Master DB properties.
a) DB_DRIVER
Description: Class name for JDBC driver used for this database.
Example: com.mysql.jdbc.Driver
b) DB_URL
770 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Installation
Description: JDBC URL to database's service
Example:
jdbc:mysql://localhost:3306/RB_DBO
c) DB_USER_NAME
For example: Database user such as dbadmin
d) DB_PASSWORD
This is the password for user account.
Default: None (must be specified prior to installation)
4. Update the mandatory properties in the updateSharedProps section.
a) MAIL_ADMIN_ADDRESS : This can be any email id such as Gmail or Yahoo.
b) MAIL_PORT_NUMBER: 465
The port used to access the mail server. This property is only valid for SMTP. The value will be ignored for
Exchange and Gmail.
Default: 25
a) MAIL_USE_SSL_STRING
Specifies the use of SSL or TLS encryption to access mail server. This property is only valid for SMTP.
The value will be ignored for Exchange and Gmail. You can set this property to:
true or 1: If your mail server uses Secure Socket Layer (SSL) encryption.
false or 0: If your mail server uses no encryption.
2: If your mail server uses Transport Layer Security (TLS) encryption.
Default: false or 0
b) MAIL_HOST_NAME
Selects the mailing option to be provided at instance level:
SMTP: Provide a valid SMTP host name, for example, smtp.gmail.com, to select SMTP as the default
mailing option.
Exchange: A value of Exchange selects Exchange as the default mailing option.
Gmail: A value of Gmail selects Gmail as the default mailing option.
Default: Null
c) MAIL_USER_NAME
The email address used for outgoing emails. This property is only valid for SMTP and Exchange. The
value will be ignored for Gmail.
Default: Null
d) MAIL_PASSWORD
The password for the mail user account. This property is only valid for SMTP and Exchange. The value
will be ignored for Gmail.
Default: Null
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 771
Chapter 13: Installing and administering Private Cloud
e) $NO_LICENSE_PROPERTY$
Replace the $LICENSE_PROPERTY$with host name. This is optional if you have license.xml in the
config directory.
f) IsSecureServer: To use the HTTPS / secure server for Private cloud instances, add the
"IsSecureServer": "TRUE" .
Configure a supported database
Configuring a supported database
Rollbase certifies use of the following databases (see Platforms supported for Private Cloud on page 757):
• MySQL
• OpenEdge Database
• Using Oracle or SQL Server Database
You should create a separate database user account for Rollbase. To improve database security Progress
recommends that you only give the following access privileges to this account: SELECT, INSERT, UPDATE
and DELETE.
The following topics describe how to configure the supported databases:
• MySQL on page 772
• OpenEdge on page 773
• Using Oracle or Microsoft SQL Server on page 774
• Adding DB Details on page 775
MySQL
If MySQL is on the same host as Rollbase, or is on another server reachable over the local network, run the
create_mysql.sql script from the sql folder in the Rollbase directory of your installation as described in
Create tables on page 772.
If you do not have MySQL installed, download and install it, using the following options:
• Install for a developer machine
• Choose a transaction database (Rollbase does not use OLAP).
• Choose online transaction processing.
• Choose utf8 as the default character set.
Verify that either the MySQL JDBC driver mysql-connector.jar, or the Progress DataDirect JDBC driver
file, mysql.jar, is in the lib directory of your Web server.
Create tables
In the ProgressRollbase\sql folder of your Rollbase installation, locate the create_mysql.sql file and
comment out the sections that do not apply to MySQL. If you installed PAS, this folder will be
Pas_Instance\Rollbase\sql.
772 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Installation
You can run the script as follows:
• On Linux or Unix machines use a Terminal service to run the mysql command, then use the source
command to run the create_mysql.sql script.
• On Windows machines, use the mysql command line tool or install MySQL Workbench. to use the
Workbench:
1. Start from the Workbench Central screen and click New Connection.
2. In a dialog enter a name for the new connection and specify a password for the root user.
3. Open the newly created connection by double-clicking it.
4. From the menu select File > Open SQL Script. Locate and open the create_mysql.sql file in
the location where you unpacked rollbase.zip.
5. Use the menu Query > Execute (All or Selection) to run the script from the opened SQL file and create
the Rollbase database rb_dbo and all tables.
6. Click Refresh in the SCHEMAS sidebar area. You should see an rb_dbo database and a list of tables
inside, such as rb_act_trail, etc.
Next, Edit node-config.json.
OpenEdge
You can install a dedicated OpenEdge database instance Using the Rollbase Installer. The Rollbase installer
sets up and configures the dedicated instance for you. To use an existing OpenEdge database, it must be the
OpenEdge Enterprise RDBMS package.
When using OpenEdge database with Rollbase, Progress recommends that you become familiar with the
physical storage structures of your Rollbase OpenEdge RDBMS instance and the many configuration parameters
for the database. This helps you to ensure an optimal performance of your Rollbase applications and reliability
of its data. To learn about OpenEdge database, see the OpenEdge Getting Started: Database Essentials and
OpenEdge Data Management: Database Administration manuals in your OpenEdge documentation set.
Additionally, if you need assistance with OpenEdge database management or administration tasks, you can
contact Progress professional services or one of the third-party Progress consulting partners.
Use the OpenEdge proenv utility to execute a script provided by Rollbase. This creates the following:
• A database and the following related artifacts in a specified folder inside your OpenEdge Work directory
• A structure definition file
• A configuration parameter file
• A database with a transaction log and data extents for four areas
• A startdb.bat or startdb.sh script to start the database
• A stopdb.bat or stopdb.sh script to stop the database
• An account for the specified user with the specified password
Note: OpenEdge has a variable length VARCHAR data type but SQL does not. Therefore, the OpenEdge Data
Dictionary definition of a VARCHAR(10) field can hold 1, 5, 10, 100, 1000, etc. characters. OpenEdge's ABL
can read or write any sized string, but an attempt to access this with SQL produces an error if the data is greater
than 10 characters. Therefore, you should set the character value of (N) large enough to prevent such errors.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 773
Chapter 13: Installing and administering Private Cloud
Preparing an existing OpenEdge instance to work with Rollbase
To configure the OpenEdge database for Rollbase:
1. Start up the Progress environment using the proenv utility, which is available from the OpenEdge bin
directory or on Windows systems, from the Start Menu under All Programs > Progress > OpenEdge
<version>.
2. Navigate to the Rollbase sql directory that contains the create_oedb script. This directory also contains
the create_oe.sql script.
3. Using the proenv utility, execute create_oedb.bat on Windows systems or create_oedb.sh on Linux
systems. This will create the Rollbase schema and database. The create_oedb script takes the following
arguments:
• -dbname dbname: The database name, which defaults to rbdb
• -port portnumber: The database port number, which defaults to 8911
• -user username -- The username, which defaults to dbadmin
• -pwd password: The password, which defaults to dbadmin
• -script filepath: Full path to the SQL script file that creates Rollbase schema for OpenEdge The
default value is create_oe.sql, which is found in the same folder as this script.
• -dbhome homefolder: The folder inside the WRK directory where the Rollbase database is created.
The default value is oe_rollbase_db. For example:
proenv > create_oedb.bat -dbname oe_rbdb -port 9911
-user rbadmin -pwd mypwd
Upon successful completion, you should see output similar to the following:
Database home is "C:\\OpenEdge\WRK\oe_rollbase_db"
Setup for database oe_rbdb COMPLETED OK
11-12-2013 11:34:51.38
You can use the command proenv> create_oedb.bat -h to display the usage information for the
script's arguments.
4. Modify the Rollbase configuration file as described in Edit node-config.json.
Note: When you congifure an existing OpenEdge database, you must convert it into an UTF-8 database to
make it compatible with Rollbase. To know more about converting OpenEdge to UTF-8 database, refer solution
mentioned here:
https://documentation.progress.com/output/ua/OpenEdge_latest/index.html#page/dvint/using-unicode-with-openedge-databases.html.
Using Oracle or Microsoft SQL Server
Oracle
To use Oracle, download and install the latest version from http://www.oracle.com if you do not already have
an Oracle instance available. The Rollbase Private Cloud download includes the Progress DataDirect JDBC
driver for Oracle, RBoracle.jar.
Use an existing Oracle user (schema) or create a new Oracle user. Then run the create_ora.sql script to
create all of the required Rollbase tables:
sqlplus> @create_ora.sql
774 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Installation
Modify the Rollbase configuration file as described in node-config.json on page 898
Microsoft SQL Server
To use Microsoft SQL Server, download and install the latest version from http://www.microsoft.com if you do
not already have a Microsoft instance available. The Rollbase Private Cloud download includes the Progress
DataDirect JDBC driver for Microsoft, RBsqlserver.jar.
Use an existing SQL Server database or create a new database. Then run the create_ms.sql script to create
all of the required Rollbase tables.
Modify the Rollbase configuration file as described in Edit node-config.json.
Adding DB Details
The node-config.json file specifies the URL, username, password, and other properties that Rollbase uses
to access the database. You need to edit this file manually in the following circumstances:
• If you did not use the Rollbase installer
• If you used the Rollbase installer, but did not choose to use the OpenEdge database
The node-config.json will be in one of the following locations:
• If you used the installer and had it install PAS:
>InstallationDir<\Rollbase\PAS_Instance\rollbase\config
• If you used the installer and did not have it install PAS
• If you are installing manually from zip files, the config folder in the location where you extracted
rollbase.zip.
Edit the file as follows:
1. Open node-config.json in a text editor.
2. At a minimum, enter values for the following properties. For a full list of properties, see the reference topic
for node-config.json
Choose from:
• Database name
• Driver
• URL (Make sure that no white space exists after the URL and before the </Url> tag.)
• DbUser (Enter credentials for the account used to execute the Rollbase create_oedb script.)
• Password
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 775
Chapter 13: Installing and administering Private Cloud
Drivers shown below are data direct drivers (except MySQL) bundled with Rollbase. Sample URLs for various
databases:
MySQL
url: jdbc:mysql://localhost:3306/RB_DBO
driver: com.mysql.jdbc.Driver
Oracle
url:
jdbc:rollbase:oracle://localhost:1521;ServiceName=RB_DBO;ConnectionRetryCount=10;ConnectionRetryDelay=10;identifySystemTables=false
driver: com.rb.jdbc.oracle.OracleDriver
SQLServer
url:
jdbc:rollbase:sqlserver://localhost:1433;databaseName=RB_DBO;integratedSecurity=true;ConnectionRetryCount=10;ConnectionRetryDelay=10
driver: com.rb.jdbc.sqlserver.SQLServerDriver
OpenEdge
url: jdbc:datadirect:openedge://localhost:9100;databaseName=RB_DBO
driver: com.ddtek.jdbc.openedge.OpenEdgeDriver
DataDirectCloud
url: jdbc:datadirect:ddcloud://service.datadirectcloud.com:443;databaseName=RB_DBO
driver: com.ddtek.jdbc.ddcloud.DDCloudDriver
Example:
{
"name": "DBONE",
"driver": "com.mysql.jdbc.Driver",
"url": "jdbc:mysql://localhost:3306/XYZ_DBO_PORT80",
"user": "",
"p455": "",
"isExternal":"No",
"poolType":"0",
"minConnections":"1",
"maxConnections":"10",
"maxInUseTimeMins":"30",
"maxNotUsedConnTimeMins":"2",
"maxConnLifetimeMins":"60",
"connTimeoutSec": "-1"
Configuring PD4ML
You can configure an HTML report to render as a PDF document during runtime. See PDF report options for
HTML Template reports on page 305 for more information.
PD4ML is a tool that uses HTML and CSS (Cascading Style Sheets) to generate PDF. You can control PDF
page size, orientation and page breaks, dynamic headers, footers, and page numbering.
Note: PD4ML rendering from HTML page to PDF is done at the server side of production servers. While
rendering the page, pd4ml may have to use styling via CSS files or generate links to Rollbase pages. These
resources are accessed/served via system's external URL. So, in order for PD4ML to work completely, it's
necessary that backend of production servers is able to access system through the server's external URL.
After you install Rollbase, set the node property font directory in all production servers.
776 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Installation
Rollbase configures the PD4ML font properties during server initialization. As part of the configuration procedure,
it will search for the pd4fonts.properties file in the rollbase_home/config folder. If not found, Rollbase uses
the font directories provided in the node-config.json file to configure the pd4fonts.properties and
the in-process pd4browser.propertiesin the rollbase_home/config folder.
The first available font directory with valid font files of type " *.tt" &" *.ot" will be used. This includes files with
extension .ttf, .ttc, .otf and any other such font files.
Note: The configuration will happen only if the PD4ML jar is in the Rollbase lib directory.
Rollbase will not re-configure the PD4ML font properties if the font properties file is found under the
rollbase_home/config folder. In case it needs to be re-created, it has to be manually deleted followed by
a Rollbase restart.
Starting components and logging In
Before logging in to Rollbase, perform the steps appropriate for your operating system:
• Starting Components on Windows Systems
• Starting Components on Linux Systems
Starting components on Windows systems
Follow these steps to start the Private Cloud components:
1. If necessary, start the database. If you used the Rollbase installer and had it install OpenEdge, the database
should be running. You can verify by doing the following:
a) Open a command prompt (on Windows systems, run it as an administrator).
b) Change directories to the oe_rollbase_db folder of your installation. If you used the default location,
this location is Progress\WRK\oe_rollbase_db.
c) If the database is running, you will see a rbdb.lk file. If not, run the startdb script.
2. Start the Web server in one of the following ways:
• If you used the Rollbase installer and installed PAS, open a command prompt as an administrator,
navigate to the Pas_Instance\bin folder, and run tcman start.
• If you installed Tomcat yourself, open a command prompt as an administrator and run the Tomcat
startup.bat script located in the bin folder of the Tomcat installation.
3. Enter the URL for your Web server in a browser. If you are using PAS, use
http://localhost:8830/router/login/loginPrivate.jsp or https://localhost:8831/router/login/loginPrivate.jsp, which
redirect you to the Rollbase login page. If you installed Tomcat using the default port, use http://localhost:8080
.
The Rollbase login page (or Tomcat home page if you are not using PAS) should open. If it does not, check
to make sure that JRE_HOME is set properly and that you have administrative privileges.
4. Log in using the temporary password from the Rollbase welcome email. When Rollbase starts, this email
is sent to the administrative email user specified in the Shared Properties on page 786. Bookmark the URL
for future use.
5. Change the temporary password.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 777
Chapter 13: Installing and administering Private Cloud
6. From the Applications drop-down menu, select System Console and verify that all components are running.
7. Verify that all applications described in Private Cloud Applications are successfully installed.
If you need to stop the OpenEdge database, run the stopdb.bat script in the work directory you specified
during installation. If you need to stop Tomcat, run the shutdown.bat script for standalone instances or stop
the service.
Starting components on Linux systems
To start the database and Tomcat on Linux you need to be running as root.
1. Start the database.
2. If you installed a new instance of Tomcat, set the JAVA_HOME environment variable to
$ROLLBASE_HOME%/jre.
3. Start the server.
• If you have installed a new instance of Tomcat, start it by running the Tomcat startup.sh script, which
by default is found in $ROLLBASE_HOME%/apache-tomcat-8.0.30/bin.
Note: Ensure that you are using Rollbase supported Apache Tomcat version.
• If you installed Rollbase using the installed and installed the PAS server, start it by running the
startup.sh script in the $ROLLBASE_HOME%/Pas_Instance/bin directory.
4. Enter http://localhost:8080 in your browser.
The Tomcat welcome page should display. If it does not, check to make sure that JRE_HOME is set properly
and that you have administrative privileges.
5. Log in using the URL and temporary password from the welcome email. This email was sent to the
Administrative email user specified in the Shared Properties on page 786 . Click the Refresh link if no data
is shown.
6. Change the temporary password.
7. From the Applications drop-down menu, select System Console and verify that all components are running.
8. Verify that all applications described in Private Cloud Applications are successfully installed.
Activating your license
You will receive your Rollbase license through email. Progress recommends saving a copy of the email message.
If you are upgrading from an evaluation license, you need to edit configuration files to use the host name you
supplied when purchasing the license. If you are simply renewing a license for the same host name, you can
upgrade the license without restarting.
The following sections describe how to activate or upgrade a license.
• Upgrading from an evaluation license on page 779
• Upgrading a license without restarting on page 779
778 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Installation
Upgrading from an evaluation license
To upgrade Rollbase Private Cloud from an evaluation version, follow these steps:
1. Edit the node-config.json in the Master and add the HostName in the node-config.json file.
2. Copy the license.xml file into the config directory.
3. Stop and restart PAS or your Web server.
Upgrading a license without restarting
To activate a license without restarting:
1. Login to Rollbase as Master admin.
2. Browse to System Console > System > Control Panel > General > License and Usage
3. In the License and Usage > License ID section, click Update.
4. Click Choose File, navigate to the location of your license.xml file, select it and click Next.
5. Confirm that you want to update your license.
Your license will be updated without restart.
Troubleshooting
The following topics describe some common problems and what you can do to resolve them:
• Installation issues on page 779
• License Errors
• Email Issues
Installation issues
When the Rollbase installer is running, it logs messages to the standard output stdoutXXX.log file (or
hostname.XXX.log) in the Tomcat log directory (if Tomcat is running as a service) or to the application's
terminal window. For normal, error-free startup you should see output similar to the following (omitting some
Tomcat-generated messages):
==>> Master Server is starting
ROLLBASE_HOME=c:\rollbase\shared
Host name: localhost:8080
Release: 4.07
Master Server: Initialization completed successfully
==>> PROD1 Server is starting
Production Server PROD1: Initialization completed successfully
==>> REST server is starting
==>> Router Server is starting
==>> SEARCH Server is starting
==>> STORAGE Server is starting
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 779
Chapter 13: Installing and administering Private Cloud
==>> WEBAPI Server is starting
These log messages are important for diagnosing installation and setup issues. Please include them in any
support request related to Rollbase Private Cloud installation.
If you encountered an error during installation, cannot start or login into your Rollbase server, the following
issues could exist:
Issue Resolution
The ROLLBASE_HOME environment variable is not set Make sure that the ROLLBASE_HOME environment
or is pointing to the wrong directory. variable is set and pointing to the correct directory.
See Set environment variables on page 769
The Tomcat server was not stopped while WAR files Stop Tomcat, delete the files from the Web server
were copied by you or the installer into the Tomcat deployment directory, as well as temporary files which
webapps directory. may have been created, including JSP cache files from
the working folder), recopy the WAR files and restart
Tomcat.
The host name specified in the System Console > Update the Shared Properties, Components and
System > Shared Properties, node-config.json node-config.json configuration file with the correct
configuration file and System Console > System > host name.
Components configuration files does not match the
actual host name you're using.
The Shared Properties contains invalid email Update the configuration file with valid email
credentials credentials.
The version date of rb_util.jar in the Tomcat lib If you installed manually, confirm that you unzipped
directory is inconsistent with the version and or date the Rollbase lib.zip into the Tomcat lib directory.
of the Rollbase WAR files.
Database issues Drop the rb_dbo table by running the SQL command:
drop database rb_dbo;
The WebAPI server is not running when you are Delete the Tomcat webapps/webapi directory and
logged into the Master Server and viewing Rollbase restart Tomcat.
Private Cloud component status.
If problems persist, feel free to use the Rollbase forum to ask questions and interact with other customers.
However, if the problem is related to the specifics of your local environment, you will probably need to involve
your IT staff.
License error
If you attempt to change the content of a license file, or if your license has expired, you will experience the
following:
• You still can start and run Rollbase.
• Every page displays the notification License Expired or Invalid.
• You can no longer create customers (tenants), but you can delete them.
780 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Administration
• You can no longer create or update user accounts.
• You can no longer create or update object records.
Email issues
If you cannot send emails from your Rollbase Private Cloud instance, check the following:
• Make sure that all email-related global settings in the Shared Properties are correct.
• If you are behind a firewall (corporate or local), verify that the firewall allows outgoing SMTP connections.
• If you are using Gmail, verify that POP/IMAP Access is enabled in your Gmail settings.
If you still cannot successfully send emails, add a SkipEmails=true setting temporarily. This will dump all
emails to standard output (the console window of Tomcat log file). This also allows you to recover the reset
password link for new users.
Login issues
If you run into a problem, fix your email settings, restart Tomcat, and use the Forgot Password link (available
from the login.jsp page). The system will reset your password and send another email to you.
In addition to creating the first administrative user account, the system will create a second administrative
account. Use this account if you are having problems logging in as the first administrative user. Delete or disable
this account when you no longer need it:
• User name: admin2
• Password: welcome
Administration
After installing Rollbase Private Cloud and performing the steps described in Starting Private Cloud Components,
you can begin using the master tenant. From the master tenant, administrative users can set up and manage
customer tenants and the Rollbase system. The topics in this section provide an overview of administration
and describe how to perform common tasks.
The procedures described in this section are the same for single server and multi-server environments. However,
to have access to full administrative capabilities, you need to log in to the master tenant.
Development sandboxes and production tenants
Progress recommends that Private Cloud installations have at least one customer tenant to use as a sandbox
for development and testing. To set this up, create a Customer object and add developers as users. Once
applications are ready, you can use the XML publishing mechanism or the Application Directory or Marketplace
portal to distribute applications to other customer tenants.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 781
Chapter 13: Installing and administering Private Cloud
System Tab Interface
This topic describes the System tab interface and associated actions.
The System is a tab that displays all the Rollbase system components and jobs which you can view, or configure
without the hassle of doing these actions in the backend and wait for system restart. This also makes the job
of system configuration, a quick and easy experience.
Access the System tab from the Application Switcher > System Console.
Tab Name Description
Components Displays the list of Rollbase components (such as server name and details)
for view and edit with component type (such as MASTER, PROD,
STORAGE, SEARCH), properties (Name and Path), Stats (number of
customers and sessions for each component), Host Name (IP address),
Time Running (duration), and Running Jobs information.
See Components for more information.
Servers Displays the list of servers that the current Rollbase instance is running
on with details such as the Host Name (IP address), Components (server
type such as REST, MASTER, ROUTER, STORAGE and SEARCH) Stats
(such as the number of threads and connections for a host), Environment,
Processor, and Memory details. It shows the list of NGINX servers
separately. You can add, delete or reload the NGINX servers.
See Servers for more information.
Databases Displays the list of databases that are currently in use. You can add a new
database, query or edit existing databases.
See Databases for more information.
Loaded Customers Displays the list of loaded customer details such as ID, Database and
Loaded At. You can view the logs for a loaded customer.
See Loaded Customers for more information.
Shared Properties Displays the list of Shared Properties by category such as General,
Customize and Limits. You can view or configure the properties from here.
782 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Administration
Tab Name Description
Backend changes are no longer needed. See Shared Properties for more
information.
Control Panel From the Control Panel, you can perform the following actions:
• Update your Rollbase license details
• Donwload Usage Report
• Re-create Lucene index
• Reset the Master cache
• Configure the email server, authentication details, and Google
integration
• Modify the details of field groups, list items, security and service levels
and default cards
• View and modify the code templates pertaining to Java, Node and PHP
See Control Panel for more information.
Note: It is recommended not to modify events, field groups and legacy
objects.
Monitoring Displays the system Monitoring and health information such as jobs and
events, system logs, audit trail and system diagnostics. See Monitoring
for more information.
Components
This topic describes the Component tab interface of the System Console.
As the name indicates, the Components tab displays a list of all the Rollbase logical components for the
administrator to view the load of each component and make suitable decisions around load-balancing.
Access the Components tab from the Application Switcher > System Console > System.
From this page, you can:
• View the current status of all servers, including information about the component type, its properties, stats
such as number of customers loaded on the servers, number of sessions, host name, the duration and
running jobs.
• View the current status of all production servers, all databases.
• Refresh the components list to view updated information for all the components.
• Edit the display name of a component.
• Click a Rollbase component name to view its information in the Component Information page. This page
displays component information such as the component, its name, type, external URL including current
status such as the instances and instance details, customer load details, currently logged-in user(s) details,
and a list of currently running job(s) (i.e., import, batch, and customer creation jobs) details.
Running Jobs
The Running Jobs table displays the list of running jobs for the selected component such as master, prod,
and storage servers.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 783
Chapter 13: Installing and administering Private Cloud
Resiliency of jobs represents the ability of jobs to recover from node failures or other external conditions. Nodes
pick up a job for execution without stepping on each other from a common database store. It is guaranteed
that a given job will be executed only once by a pool of nodes. Rollbase supports multiple job pools for a
customer/tenant which are as follows:
• Delayed Trigger jobs
• Batch jobs
• Import jobs
• Large jobs
• Mail jobs
Note: For a customer, only 1 job from each pool is executed in parallel. Not more than 1 job from the same
pool is executed.
When a node is down, all jobs move from running status into a waiting status. The idea is to ensure that in
case of an error, a job is eventually executed. Import jobs and MassRun jobs support progress tracking when
a node fails and another node picks it up. All other job types are restarted and executed from the beginning.
All jobs that are in a waiting state can be cancelled. The following jobs can be cancelled only when they are in
a running state.
• Data Maintenance
• MassRun
• SfdcImport
• MoveStorage
• SystemBackup
• SystemRestore
• Import
• MsAccessImport
Note: Any batch job in waiting status can be cancelled from the System Console > Monitoring > Jobs >
Action. However, a running batch job cannot be cancelled. See Monitoring > Jobs for more information.
Example: Cancelling an Import job. Consider an Import job that involves importing 1000 records
wherein, 480 records have already been imported and 520 records are pending import. At this point,
if this import job is cancelled, the cancel operation impacts the remaining 520 records pending import.
However, for the 480 records that were already imported, Rollbase sends an email notification to the
customer/user.
Note: As a best practice, always consider the impact of the cancel operation on a job when it is in
running state. For example, certain job types such as SystemRestore should be cancelled understanding
the fact that it may render the tenant in an unsuable state.
Servers
This topic describes the Servers tab interface of the System Console.
This page displays the server information for the Rollbase application.
784 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Administration
Access the Servers tab from the Application Switcher > System Console > System.
You can perform the following operations in this page:
• Refresh the Servers page to view updated server(s) information pertaining to the Host Name, Components
Stats, Environment, Processor and Memory.
• Click a server record's Host Name (IP address) link to view the server information. To view detailed server
information, click the tabs - Components, System Info, Memory, Libraries and Configuration Files.
• Click the Threads value (number shown as a link) to view the threads running for the selected server.
• Click the Connections value (number shown as a link) to view the connection details such as ID, Database,
Customer ID, it's creation date, etc. You can also view Log details, and Refresh the view. Cleanup enables
cleanup and closes all idle connections. This helps the administrator to ensure that number of connections
in any association do not exceed the specified threshold.
• The NGINX Servers displays the list of Nginx servers and it's server details. You can also Reload the Nginx
server information.
• Click +Server to add a new Nginx server or click Action > Del to delete an Nginx server and its related
details.
Databases
This topic describes the Databases tab interface of the System Console.
This page displays the databases information for the Rollbase application.
Access the Databases tab from the Application Switcher > System Console > System.
You can perform the following operations in this page by specifying the URL, username, password, and other
properties that Rollbase uses to access the database:
• Refresh the Databases page to view updated databases(s) information pertaining to Host Name, Type
Pool, Version, Is Master, Is Default, Connections, Customersand Records.
• Click + Database to create a new database.
Create Database > Database Info
Specify the Database Name, select the Database Type, specify the JDBC Driver, Database URL; specify
the User Name and Password to access the database.
Enable Use this database as default for new Customers and/or This database includes External tables
which can be mapped as system objects.
Click Test Database Connection to check that it is working.
Create Database > Connections Pools Options
This section displays the default values for Pool Type, Min Connections, Max Connections, Max Time
In Use, Max Idle Time, Max Life Time and the Transaction Isolation fields. Specify the required information
for these fields including New Connection Timeout and Save. Alternatively, Cancel the + Database, if not
required.
• Under the Action column, click Query to select an existing database to make queries, view the database
schema and external tables, if any and print the QueryDatabase page details.
• Under the Action column, click Edit to view and modify existing database information and Save details.
Alternatively, Cancel the Edit operation.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 785
Chapter 13: Installing and administering Private Cloud
Loaded Customers
This topic describes the Loaded Customers tab interface of the System Console.
This page displays the loaded customer information for the Rollbase application.
Access the Loaded Customers tab from the Application Switcher > System Console > System.
You can perform the following operations in this page. To perform page level operations such as View Logs,
Login and Edit or More Actions, see working with customer records.
• Loaded Customers
Refresh the Loaded Customers page to view updated information pertaining to Customer, ID, Database
and Loaded At.
Under the Action column, you can View Logs for each customer.
Click a record in the Customer column to view a loaded customer's details in the Details view such as
Account Information, Runtime Information, Subscription Information, Zone Properties, First Administrative
User, Address Information, Language Settings, Global Settings, Email Settings, Cloud Storage, System
Information and ISV Partners.
• Loaded Customers > Details
In the ISV Partners section, Attach User, click Columns to select the column view or Reset, Filter and/or
Flag the ISV Partner information.
Shared Properties
This file stores system-level properties to be shared among all Rollbase components. Each property is placed
on a separate line in the following format:
key = value
The table below lists all available properties and their default values. A few important properties to note:
• The HostName property defaults to localhost:8080 To use a different host name or port, adjust this
property accordingly, or your server will not start.
Access the Shared Properties tab from the Application Switcher > System Console > System.
From the Application Switcher > System Console > System > Shared Properties > General > Platform
define, modify or view the below properties
Platform Property Description
HostName Host name of your master server.
Default for Tomcat: localhost:8080
Default for PAS: localhost:8830
To use HTTPS for access, the default port numbers are 8081 and
8831, respectively.
786 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Administration
Platform Property Description
Note: This property appears as a Platform property for a Rollbase
instance that has no licensing information and needs a restart. For
a licensed Rollbase instance, the HostName appears in the Control
Panel > General > License and Usage
TitleTemplate The template for a page's title. Can be overridden by ISV partners.
See Creating and managing customer tenants on page 946 for more
information.
Default:{!A} | {!S} | {!P}
DefaultLangCode ISO language code used by default (when no language selection
is made or available)
Default: en (English)
DefaultDateFormat Index of date/time format used when no selection is made or
available, use a type supported by Rollbase
Default: US date/time format
TimeZones A comma-separated list of time zones. If required, add to this list
any TimeZone IDs which are a part of
TimeZone.getAvailableIDs().
Default: None
Encodings Encoding support for comma-separated list files.
Default: ISO-8859-1,US-ASCII,UTF-8
CustWeight The coefficient to be used in a formula to calculate load on a
particular production server (only used in multi-server edition).
Defaults to 3.
CustomClassFilter You can use custom Java objects (available on CLASSPATH) in
Rollbase formulas. This property lets you specify the classes to
allow in formulas. Specify a RegEx expression that matches classes
you want to allow. For example, if you want to use a variable of
the type java.util.ArrayList(), you would include the entry
CustomClassFilter=java.util.ArrayList. See
http://www.w3schools.com/jsref/jsref_obj_regexp.asp for more
information about RegEx expressions.
JSOptimizationLevel Optimization makes the compiler attempt to improve the
performance and/or code size at the expense of compilation time
and possibly the ability to debug the program.
Simple data and type flow analysis is performed to determine which
JavaScript variables can be allocated to Java VM registers, and
which variables are used only as Numbers. Local common
sub-expressions are collapsed (currently this only happens for
property lookup, but in the future more expressions may be
optimized). All local variables and parameters are allocated to Java
VM registers. Function call targets are speculatively pre-cached
(based on the name used in the source) so that dispatching can
be direct, pending runtime confirmation of the actual target.
Arguments are passed as Object/Number pairs to reduce
conversion overhead.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 787
Chapter 13: Installing and administering Private Cloud
Platform Property Description
See
https://developer.mozilla.org/en-US/docs/Mozilla/Projects/Rhino/Optimization
for detailed information.
UnloadCustAfterMins Unloads the customer from the cache after period of time (in
minutes)
Default: 60
CloudType When set to AWS the cloud instance type information is retrieved
and displyed in System Console > Servers Tab.
Note: You should set the value to AWS only if Rollbase is deployed
on AWS.
Default: Default
When set to Default, the cloud instance type information is not
fetched.
From the System Console > System > Shared Properties > General > Add/Remove Features define, modify
or view the below properties.
Add/Remove Features Description
AllowAdminLessTenant When set to true, this property enables tenants without
administrative users. Does not apply to the master tenant.
Default: false
GettingStartedEnabled When set to false, this property makes the Getting Started
component unavailable in the page editor.
Note that if any of your pages use the Getting Started
component, you must manually remove the component and save
the page using the page editor for the Getting Started
component.
Default: true
SupportCorticonService Support managing Corticon service integration in Rollbase. When
set to false, the service is not supported. Default value is true.
SupportDataDirectCloud Support for managing Data Direct Cloud objects in Rollbase.
When set to false, the service is not supported. Default value
is true.
SupportOEService Support for managing OpenEdge service objects in Rollbase.
When set to false, the service is not supported. Default value
is true.
SupportRemoteDatabase Support for external tables in a remote database that is not used
as the Rollbase database. When set to false, the service is not
supported.Default value is true
SupportProgressDataCatalog Support for managing Progress Data Catalog for Telerik/Mobile
app integration. When set to false, the service is not supported.
Default value is true.
788 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Administration
Add/Remove Features Description
AllowMultipleRestSessions When set to true, this property enables multiple REST API
sessions per user. That is, Rollbase can create multiple
concurrent sessions for the same user and process the REST
API calls from all the sessions.
Default: false
IsPDFAnnotationEnabled When set to true, the Enable PDF Annotation checkbox
associated with the File Upload field is visible to enable the PDF
editor function on the PDF files.
Default: true
AppInstallOverridesChanges At customer tenant creation, controls whether conflicting
application changes will be ignored or will override the existing
component. The Customer record contains a list of applications
that Rollbase will install automatically. These applications are
installed in the order in which they appear in that list. If an
application contains a component that already exists, this property
determines whether conflicting changes will be applied(true)
or ignored (false). Additive changes are always applied. For
more information, see Installing applications in new tenants
automatically.
Default: false
CustomValidationViaAPI When set to true, this property enables all validations required
before executing an API operations. Therefore, any operations
performed using the product UI and API will be validated.
Default: true
SkipEmails Do not send email messages; dump them on standard output
instead. Use this option for the development version when no
outbound email is available. Default: false
EmailSettingsOverrideAtCustomer When set to true, this property enables you to set up a custom
email server for your tenant. This property makes available Email
Server Settings in the Administration setup page.
Default: true
CheckLoginURL Enables system health check and sends status emails to Rollbase
admin if health check fails.
If set to false, the system health check is disabled.
Default: true
Rollbase server code pings itself on its login URL, periodically,
to monitor the system's health. That is, it checks the accessibility
of the login page.
For this, you must ensure that the router component’s external
URL is accessible from master component and firewall/network
settings are configured to allow this health check.
IsAsposePDFParserEnabled Enables you to use Aspose Parser for all PDF documents.
Default: false
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 789
Chapter 13: Installing and administering Private Cloud
Add/Remove Features Description
See Working with customer records on page 825 for more
information.
IsAsposeDocParserEnabled Enables you to use Aspose Parser for all Word documents with
doc extension.
Default: false
See Working with customer records on page 825 for more
information.
IsAsposeDocxParserEnabled Enables you to use Aspose Parser for all Word documents with
docx extension.
Default: false
See Working with customer records on page 825 for more
information.
From the System Console > System > Shared Properties > General > Security define, modify or view the
below properties
Security Property Description
PasswordActivationLinkExpiry Set the password expiration time in hours for reset
password link for existing users request to reset password.
Default expiry time of the link: 2 hours
NewUserPasswordActivationLinkExpiry Set the password expiration time in hours for new user
activation link to expire.
Minimum: 1
Default expiry time of the link: 2
.
InactiveSessionExpireMins Time of user's inactivity (in minutes) before user session
expires
Default: 240
LoginSessionExpireMins Time from the user's login (in minutes) before the user
session expires.
Default: 480
ProgressDataServiceCORSHost Specifies the online address of the Progress Telerik host.
This enables Telerik applications to access Rollbase
services. Defaults to
.*.(progress|icenium|telerik).com$
IsSecureServer Determines the security protocol for all communications
between your browser and the website.
Default: false
From the System Console > System > Shared Properties > General > System Jobs define, modify or view
the below properties
790 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Administration
System Jobs Property Description
CleanupMins Interval in minutes between cleanup operations on each
component
Default:60
PurgeAfterDays Rollbase purges deleted records from the Recycle Bin after
the specified number of days
Default: 30
PurgeRecordsBatchSize Indicates the batch size of records to be purged from the
Recycle Bin in a single transaction.
Default: 100
StatsCollect The time frequency with Rollbase collects tenant statistics,
stores them into backend and notifies about its execution.
Default: 3 minutes
StatusCheck Interval in minutes between status checks on each
component.
Default:5 minutes
WebProxyStatusCheck Denotes the interval in seconds between status checks on
each Web Proxy configured in Rollbase. A periodic thread
runs during the configured interval and keeps pushing the
current upstream topology to each of the configured Web
Proxy.
Default: 30 seconds
Note:
• Any change to this shared property requires a Rollbase
cluster restart.
• For example, a Web Proxy is an NGINX server added
in Rollbase.
EventCheckMins Interval in minutes between checks to run matured delayed
triggers.
Default: 1 minute
CleanupDays Delete log and backup files older than specified number
of days (if specified value > 0).
Default: 0
BatchJobsExecutorThreadCount Enables multiple threads to process batch jobs for different
customers. While only one job for any given customer will
be running at any point of time, multiple jobs for different
customers can run in parallel based on the number of
threads configured. Set a value (1 to 50) for the thread
count for the Executor Service that runs the batch jobs.
Default: 1
Max value: 50
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 791
Chapter 13: Installing and administering Private Cloud
System Jobs Property Description
Note: Configuring the
BatchJobsExecutorThreadCount property to 50 is
not recommended, as it might render the system unstable.
DelayedTriggersExecutorThreadCount Indicates the number of threads that need to be completed
before triggering the subsequent thread.
Default: 1
ImportJobsExecutorThreadCount Enables the customers to set the thread count of the import
job scheduler that runs import jobs simultaneously. Set a
value (1 to 10) for the thread count for the import job
scheduler that runs the import jobs.
Default: 1
Max value: 10
ResourcesCheck The amount of time (in hours) to wait between checking
that customers have not exceeded their limits on resource
usage (number of records, etc).
The MASTER ResourcesCheck and the STORAGE
ResourcesCheck properties must be set together.
Default: 1
From the System Console > System > Shared Properties > General > Email define, modify or view the
below properties
Email Property Description
AdminEmail Email address of the first administrator user created during
installation
Default: None (must be specified prior to installation)
AutoReplyAddress Email address used as reply-to when no other address is provided
Default: same value as AdminEmail
EmergencyAddress Email address to receive emergency notifications when an system
component is unavailable, number of threads or database
connections exceeds a threshold, or another serious error occurs.
Default: copied from AdminEmail property
MailTimeoutSec The number of seconds before Rollbase gives up when trying to
connect to the mail server. This property is only valid for SMTP
and Gmail. The value will be ignored for Exchange.
Default: 5 seconds
EmailEncodings Determines the supported email encodings. Its value is a
comma-separated list of encodings with the default encoding as
the first item in the list. Defaults to
UTF-8,ISO-8859-1,US-ASCII, with UTF-8 as the default
encoding. To override the default, set the value to a
comma-separated list of encodings with the encoding you want
792 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Administration
Email Property Description
as the default as the first item in the list, for example,
ISO-8859-1,UTF-8,US-ASCII.
From the System Console > System > Shared Properties > General > Search define, modify or view the
below properties
Search Property Description
MaxSearches Maximum number of conditions to be used in a Detailed Search
component.
Default: 20
MaxSearchResults Max number of search results to bring back for a single full text
search.
Default: 200
UseZipSearch Enable search by distance from ZIP/postal code. Enabling this
setting requires that RB_ZIP_CODES table be populated with
actual data - not supplied with Private Cloud
Default: false
IndexChangeSyncDelaySecs Max time (in seconds) between an index change and it being visible
for search.
Default: 5 secondsseconds
LockTimeoutSec Timeout, in seconds, to obtain a lock for index writing.
Default: 30 seconds
RAMBufferMB Size of RAM buffer, in MB, for indexing operations.
Default: 64MB
CloseAfterMin Remove metadata from cache if it is not being used for specified
number of minutes.
Default: 60 mins
From the System Console > System > Shared Properties > General > Log define, modify or view the below
properties.
Log Property Description
LogFormat The log4j format for log messages.
Default: [%d] %m%n
LogFileSize Maximum size of particular log file, such as main.log.
Default: 300KB
MaxBackupIndex Determines how many backup files are kept before the oldest is
erased.
Default: 1
From the System Console > System > Shared Properties > General > Database define, modify or view the
below properties.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 793
Chapter 13: Installing and administering Private Cloud
Database Property Description
D2C_URL Specifies the DataDirect URL where all objects of type DataDirect
reside. You can set this to true or false.
Default URL:
jdbc:datadirect:ddcloud://service.datadirectcloud.com:443
SQLSpecialChars A comma-separated list of SQL special characters of your database.
Progress recommends that you verify and add any special characters
in this property before generating SQL queries for external objects.
Default: All the terms identified by SQL as a special character.
SQLKeywords It is a comma-separated SQL keywords of your database.
Progress recommends that you verify and add any reserved keywords
in this property before generating SQL queries for external objects.
Default: All the terms identified by SQL as a keyword.
From the System Console > System > Shared Properties > General > API define, modify or view the below
properties.
API Property Description
UseISODateFormatInRESTJSON Enables all the REST API requests with JSON output format to return
the date or date/time values in ISO format. You can set this to true
or false.
Default: true
For example:
• If the date and time value is Mon Jul 30 00:01:00 IST 2018
its equivalent ISO formatted value 2018-07-29T18:31:00Z-
is returned.
• If the date value is Mon Jul 30 2018, its equivalent ISO
formatted value 2018-07-30 is returned.
UseISODateFormatInRESTXMLQuery Enables all the REST SELECT query API requests with XML output
format to return the date or date/time values in ISO format. You can
set this to true or false.
Default: true
For example:
• If the date and time value is Mon Jul 30 00:01:00 IST 2018
its equivalent ISO formatted value 2018-07-29T18:31:00Z-
is returned.
• If the date value is Mon Jul 30 2018, its equivalent ISO
formatted value 2018-07-30 is returned.
From the System Console > System > Shared Properties > Customize > User Interface define, modify or
view the below properties.
794 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Administration
User Interface Property Description
EnableNUIForAll Switches all tenants/customers to the new UI.
The new UI is not enabled for all tenants/customers by default.
If an administrator wants to enable the new UI for all
tenants/customers, this property must be added from
Administration Setup > Preferences.
Default: false
NewUIMobileUsesJqueryMobileUI Based on this property Rollbase renders different UI in mobile
devices. If this property is set to true, Rollbase applications
renders in classic jQueryMobileUI widgets. We are not doing
any active development on this jQueryMobile UI, so Rollbase
recommend customers to upgrade NewUI and set this property
to false to have support for Responsive UI rendering in the mobile
devices.
Default: false
DefaultUIBlueprint Default UI blueprint use for Application during Application creation
or for old Applications Blueprint is not set. There are two types
of Blueprint Rollbase support, Modern Blueprint and Vertical
Blueprint. You can set this to true or false.
Default:
String.valueOf(UITemplates.UI_TEMPLATE_MODERN_VERTICAL.getType()
DisableNUIBanner Disable Banners shows for all evaluation users who had enabled
NewUI support.
Default: false
PacificUIDisabled Disable Pacific theme UI from setup pages, classic UI and from
Page designer.
Default: false
nuiRevisedGridControl Preference stating if Revised GridControl UI component should
be rendered in form pages instead of legacy GridControl
component (applies only when NUI is enabled). This is basically
a Tenant level preference, however, if not specified at tenant
level will default to System level preference i.e. shared property.
This property is provided for facilitating migration from old grid
control to new grid control. Customers should migrate as soon
as possible as old grid control is deprecated.
Default: true
PdfFontFamily Add and configure more fonts to support different languages
(For eg- Droid Sans Fallback for Chinese). You can update the
value of 'PdfFontFamily' field with desired fonts in Setup Home
> Administration Setup > Preferences. If a preferred font value
is specified, it will be used to generate the pdf. Alternatively, if
a preferred font value is not specified, then the value of the
shared property will be used.
The font-family mentioned in this field is considered as the defualt
font. Lato, Helvetica, Arial, Tahoma and sans-serif are available
as default fonts.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 795
Chapter 13: Installing and administering Private Cloud
User Interface Property Description
IncludeShortCutIcons Check this option to include Fav, Touch & Tile icons for Desktop,
Android & iOS touch devices. These icons will be displayed when
user adds Rollbase pages as Add to Desktop, Add to Home ,
Add to Favorites, Add to Bookmarks, Pin to Start Menu (Windows
10). By default, this option is disabled.
When you enable the IncludeShortCutIcons shared
property on private cloud, ensure to copy the below icons in the
$ROLLBASE_HOME$/personalize/images folder. These
icons will be included for Application pages, Setup pages, Portal
Pages, Market place & login pages.
Note: As the name implies, the dimension for the icons ( width
X height ) is suffixed to the icon name. Private cloud customers
must design the icons according to the dimension of the icon
name to ensure for a good quality image when Rollbase pages
are added as mentioned above.
• favicon-16x16.png
• favicon-32x32.png
• favicon-96x96.png
• favicon-160x160.png
• favicon-192x192.png
• mstile-150x150.png
• apple-touch-icon-57x57.png
• apple-touch-icon-114x114.png
• apple-touch-icon-72x72.png
• apple-touch-icon-114x114.png
• apple-touch-icon-60x60.png
• apple-touch-icon-120x120.png
• apple-touch-icon-76x76.png
• apple-touch-icon-152x152.png
• apple-touch-icon-180x180.png
MSTileIconBGColor Microsoft Tiles color for Windows 10 and Windows phone. This
shared property is applicable only when the
IncludeShortCutIcons shared property option is enabled.
Provide the value in a hexa-decimal format.
Default value: #da532c
MaxRecordsInSelector Configure the maxmimum number of records for selection based
on the business need. The configured changes will be reflected
in the ListView, Grid Control, Multi-select pick-list, record attach,
796 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Administration
User Interface Property Description
ListView filters, Custom report filter fields of the New, Edit, Mass
update, Quick Create and Status change pages.
Default number of records configured: 100
Minimum number of records that can be configured: 1
Mamixum number of records that can be configured: 1000
.
From the System Console > System > Shared Properties > Customize > HTML Editor define, modify or
view the below properties.
HTML Editor Property Description
HideHtmlEditorMenu When set to true, this property hides the HTML editor menu bar.
Default: false
HtmlEditorButtonRow1 Specifies the shortcut options of the first toolbar row (of the HTML
editor) and its formatting. When this property is not set, this toolbar
is disabled.
Default: bold,italic,underline,
|,forecolor,backcolor,|
alignleft,aligncenter,
alignright,alignjustify,|,
bullist,numlist,|,outdent,
indent,blockquote,|
,undo,redo,|,link,unlink,|
,image,|,table,emoticons,
|,fontselect,fontsizeselect,
|,code,fullscreen,preview
HtmlEditorButtonRow2 Specifies the shortcut options of the second toolbar row (of the
HTML editor) and its formatting. When this property is not set,
this toolbar is disabled.
Default: <blank>
From the System Console > System > Shared Properties > Customize > Images define, modify or view
the below properties.
Images Property Description
ImageWidthFormFactorLaptop This property is applicable only when customer enables Dynamic
Image resize Settings from the Preferences page. When a user
uploads image for ImageUpload field, Rollbase generates
various images for different devices on demand. This property
applies to laptop or higher resolution devices. This property is
expressed in pixels unit.
Default: 992
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 797
Chapter 13: Installing and administering Private Cloud
Images Property Description
ImageWidthFormFactorMobile This property applicable only when a customer enables Dynamic
Image resize Settings from the Preferences page. When a user
uploads image for ImageUpload field, Rollbase generates
various images for different devices. In this property, you can
provide image size as pixel value in number format for smart
phones.
Default: 480
ImageWidthFormFactorTab This property is applicable only when a customer enables
Dynamic Image resize Settings from the Preferences page.
When a user uploads an image for ImageUpload field, Rollbase
generates various images for different devices. In this property,
you can provide image size as pixel value in number format for
Tablets.
Default: 768
ImageWidthThumbnail This property applicable only when customer enables Dynamic
Image resize Settings from the Preferences page. Rollbase
generates a thumbnail image for the uploaded image to render
it in ListView Grid column. You can provide the size of image
as pixel value in number format.
Default: 50
From the System Console > System > Shared Properties > Customize > CDN define, modify or view the
below properties.
CDN Property Description
UseCdnForNewUI To enable CDN support in the NewUI and portal pages. When
this property is enabled, user should provide a valid URL for
KendoCdn, BootstrapCdn, FontAwesomeCdn, LatoFontCdn
properties.
Default: false
BootstrapCdn CDN URL to load Bootstrap library files. This is applicable only
when user enable UseCdnForNewUI property.
Default: Null
KendoCdn CDN URL to load kendo library files. This is applicable only
when user enable UseCdnForNewUI property.
Default: Null
FontAwesomeCdn CDN URL to load FontAwesome files. This is applicable only
when user enable UseCdnForNewUI property.
Default: Null
LatoFontCdn Google font URL to load Lato font css file. This is applicable
only when user enable UseCdnForNewUI property.
Default: Null
List of CDN Servers
798 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Administration
As long as the CDN URL follows the expected pattern, you should be able to use it without any problems. The
typical pattern is a base url followed by a version and then followed by the library name.
See CDN Support for more information.
Note: The shared property contains only the base URL (ending with /) because several files can be served
from this path for all CDNs except in the case of LatoFontCdn. You may choose to use any other CDN server(s)
apart from the ones listed in this document.
Here's a list of tested CDNs:
Lato Font
http://fonts.googleapis.com/css?family=Lato:300,400,700&subset=latin,latin-ext
Kendo
Kendo CDN - http://docs.telerik.com/kendo-ui/intro/installation/cdn-service
The minified versions of all JavaScript files are available at:
• https://kendo.cdn.telerik.com/VERSION/js/FILENAME.min.js
• https://kendo.cdn.telerik.com/VERSION/styles/FILENAME.min.css
Bootstrap
MaxCDN:
• https://maxcdn.bootstrapcdn.com/bootstrap/3.3.7/css/bootstrap.min.css
• https://maxcdn.bootstrapcdn.com/bootstrap/3.3.7/js/bootstrap.min.js
Cloudflare:
• https://cdnjs.cloudflare.com/ajax/libs/twitter-bootstrap/3.3.7/css/bootstrap.min.css
• https://cdnjs.cloudflare.com/ajax/libs/twitter-bootstrap/3.3.7/js/bootstrap.min.js
jsDelivr
• https://cdn.jsdelivr.net/bootstrap/3.3.7/js/bootstrap.min.js
• https://cdn.jsdelivr.net/bootstrap/3.3.7/css/bootstrap.min.css
JQuery
Google
• https://ajax.googleapis.com/ajax/libs/jquery/1.12.4/jquery.min.js
• https://ajax.googleapis.com/ajax/libs/jqueryui/1.12.1/jquery-ui.min.js
• https://ajax.googleapis.com/ajax/libs/jqueryui/1.12.1/themes/smoothness/jquery-ui.css
MaxCDN
• https://code.jquery.com/jquery-1.12.4.min.js
• https://code.jquery.com/ui/1.12.1/jquery-ui.min.js
CloudFlare
• https://cdnjs.cloudflare.com/ajax/libs/jquery/1.12.4/jquery.min.js
• https://cdnjs.cloudflare.com/ajax/libs/jqueryui/1.12.1/jquery-ui.js
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 799
Chapter 13: Installing and administering Private Cloud
jsDelivr
• https://cdn.jsdelivr.net/jquery/1.12.4/jquery.min.js
• https://cdn.jsdelivr.net/jquery.ui/1.11.4/jquery-ui.min.js
Microsoft
• http://ajax.aspnetcdn.com/ajax/jQuery/jquery-1.12.4.min.js
• http://ajax.aspnetcdn.com/ajax/jquery.ui/1.12.1/jquery-ui.min.js
Yandex:https://yastatic.net/jquery/1.12.3/jquery.min.js
FontAwesome
MaxCDN:https://maxcdn.bootstrapcdn.com/font-awesome/4.7.0/css/font-awesome.min.css
CloudFlare:https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.7.0/css/font-awesome.min.css
jsDelivr: https://cdn.jsdelivr.net/fontawesome/4.7.0/css/font-awesome.min.css
From the System Console > System > Shared Properties > Customize > White Label define, modify or
view the below properties.
White Label Property Description
SystemName In the Rollbase Private Cloud evaluation version, this property
sets the link displayed in the upper-left corner of each page.
Typically, this link is set to navigate to your web site.
In the Rollbase Private Cloud licensed version, this property is
configured in license.xml file.
Default: Rollbase
WebSiteURL URL to root of your web site
Default: http://HostName or https://HostName. The
default value depends on the protocol decided based on
IsSecureServer and host_name by HostName shared
properties set.
Note: The WebSiteHTTP and WebSiteHTTPS shared
properties have been replaced by the WebSiteURL shared
property. Therefore, you must now use WebSiteURL for
usecases such as redirecting to a website, custom header/footer
link, and powered by button in portals.
Copyright Copyright string displayed on the bottom of each page.
Default: None
ForumURL URL to forum page; if not set, the Rollbase Forum menu is not
available in the Rollbase menu.
Default: None
LinkPrivacy Link to the Privacy Statement page on your website to be
rendered at the bottom of each page
Default: None (no link is rendered in this case)
800 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Administration
White Label Property Description
LinkSecurity Link to the Security Statement page on your website to be
rendered at the bottom of each page
Default: None (no link is rendered in this case)
LinkTerms Link to the Terms of Service page on your website to be
rendered at the bottom of each page
Default: None (no link is rendered in this case)
MarketplaceFreeTrialURL Specifies the URL of the page to which a user is redirected if
the user clicks "Free Trial" for an app on the Marketplace.
Further instructions to install the app are available on that page.
MarketplaceURL Specifies the URL for the Marketplace homepage, which is
installed separately.
To enable the Marketplace, specify
http(s)://$HTTP_PORT$/master/marketplace/ as the
property value. For example, if your HTTP port is,
private.company.com, your Marketplace URL will be,
http://private.company.com:80/master/marketplace/.
If this property is commented out or if there is no value, the
Rollbase Application Directory is enabled and Marketplace
is disabled for your tenant. For information about publishing and
distributing applications to Rollbase Application Directory and
Marketplace, see Publishing and distributing applications on
page 691.
Default: Null
Note: Starting with Rollbase 4.0, in Rollbase Private Cloud,
Marketplace is provided as an alternative to Application
Directory. The new Marketplace provides more features and a
better user experience for publishing and distributing
applications.
SupportTicketURL Specifies the URL of the Support Tickets link in the footer of
your Rollbase instance. Comment-out the property to hide the
Support Tickets link. When left blank, the Support Tickets
link navigates to a Progress Rollbase support page where users
can raise a support ticket for the master tenant to acknowledge.
Default: <blank>
SupportURL Specifies the URL of the Support link in the footer of your
Rollbase instance. Typically, you direct your users to a Web
page where they can get product support.
Default: http://www.progress.com/support-and-services
SubscribeNowURL URL to be invoked when a user clicks Buy Now (this button is
displayed in the banner for trial customers)
Default: None (Buy Now will redirect to the support portal if this
setting is not filled)
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 801
Chapter 13: Installing and administering Private Cloud
From the System Console > System > Shared Properties > Customize > Documentation & Help define,
modify or view the below properties.
Documentation & Help Property Description
NewOnlineHelpBaseUrl Specifies the base URL that will be appended to context-sensitive
Learn More links in the UI for users. If you change this URL, you
must also supply content in WebWorks Reverb Help format (with
context IDs), or the links will not work.
Default:
http://documentation.progress.com/output/rb/doc/index.html#context/rb/
UseDocxHelp The property used to hide/show the Learn Morelinks throughout the
product.
Default: true
ShowHelpTips When set to false, this property hides all the help tips and the Help
Me button in the footer of your Rollbase instance.
Default: true
CreateNewAppVideoURL Specifies the URL to a user assistance video on how to create an
application using Rollbase quick create wizard.
Default:
https://documentation.progress.com/output/ua/redir/RB_quick_create.html
The Rollbase Getting Started page contains a link to this video. To
substitute your own video, you should supply a valid URL to an
embeddable video.
CustomizeAppVideoURL Specifies the URL to a user assistance video on how to customize
an application using Rollbase.
Default:
https://documentation.progress.com/output/ua/redir/RB_customize_ovr.html
The Rollbase Getting Started page contains a link to this video. To
substitute your own video, you should supply a valid URL to an
embeddable video.
NavAppVideoURL Video URL that explains how to customize the Rollbase application.
FastTrackPage Specifies the URL to the Progress Rollbase Fast Track page which
contains the Quick Start tutorial, companion videos, and online help
links.
Default: http://documentation.progress.com/output/rb
ShareYouAppVideoURL Specifies the URL to a user assistance video on how to expose a
Rollbase application to end users.
Default:
https://documentation.progress.com/output/ua/redir/RB_share_ovr.html
The Rollbase Getting Started page contains a link to this video. To
substitute your own video, you should supply a valid URL to an
embeddable video.
VideosWebinarsURL Specifies the URL to Progress webinars and videos.
Default: https://www.progress.com/video#filter=.pm2.pp8,.pm3.pp8
802 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Administration
Documentation & Help Property Description
The Rollbase Getting Started page contains a link to this video. To
substitute your own video, you should supply a valid URL to an
embeddable video.
From the System Console > System > Shared Properties > Limits > System define, modify or view the
below properties.
System Property Description
ExpirationDays Number of days for free trial to SaaS customers (if 0, the Free Trial
box will not be displayed in the sidebar and trials will have no
expiration date).
Default: 30
NextIDBatchSize Determines the batch size or how many IDs must be reserved for
the next batch of IDs so that throughput is high. It accesses the
database each time it gets another batch of IDs, and is best for
performance purposes to make batch sizes comparatively large but
unused IDs are lost forever. Generates IDs for records and metadata.
Default: 1000
MaxAjaxPerSession Maximum number of AJAX API calls per user login session
Default: 1000
MaxAlarmThreads The system will send a message to admin if number of Java threads
exceeds this value.
Default: 200
MaxCachedEntities Maximum number of object records cached by servers. If set to 0,
no caching is enabled.
Default: 1000
MaxFileSizeKB Maximum size in KB for upload files.
Default: 5120
HttpConnKeepAliveTimeout Indicates the minimum amount of time an idle connection has to be
kept open (in seconds).
Default: 15 seconds
HttpConnKeepAliveMaxReq Indicates the maximum amount of requests that can be sent on a
connection before closing it.
Default: 100 requests
Note: This property is not applicable if you are running Rollbase in
Apache. You will have to directly configure keep-alive settings in
Apache.
MaxHTTPParamLength Maximum size (in chars) of HTTP parameters processed by the
system.
Default: 80000
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 803
Chapter 13: Installing and administering Private Cloud
System Property Description
MaxHttpRetryTimeoutInMins Specifies the maximum HTTP retry timeout value (Retry Interval *
Number of retries).
Default: 1 min
RetryTaskTime Specifies the maximum FTP retry timeout value.
Default: 3000 ms
From the System Console > System > Shared Properties > Limits > Views & Charts define, modify or view
the below properties.
Views & Charts Property Description
MaxChartCols Maximum number of columns displayed in charts
Default: 1000
MaxFilters Max number of filters for views.
Default: 5
MaxFormulaSize Maximum size (in characters) of parsed formula. This size is
checked before sending formula to JavaScript Engine.
Default: 10240
MaxListTotals Maximum number of columns with totals in views and reports
• Minimum value: 0
• Maximum value: 5
Default: 3
MaxQueryLength Maximum number of characters in a query sent to Query API
Default: 2000
MaxReqsInQuery Maximum number of records which can be fetched by SQL query
Default: 20,000
From the System Console > System > Shared Properties > Limits > Import & Export define, modify or
view the below properties.
Import & Export Property Description
MaxExportRows Maximum number of report rows to be exported as
spreadsheet and max number of items in drop-down
lookup. Important: for Oracle database this value cannot
exceed 1000
Default: 10000
MaxRecordsAllowedInReporting Maximum number of records to be used in reporting.
Default: 10000
MaxSeedRecords Maximum number of object records that can be attached
to an application. This property is not present in the
shared.properties file by default. You can add this if
required.
804 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Administration
Import & Export Property Description
Default: 15000
MaxSyncImportFileSize When importing data from an Excel or CSV file, the
maximum size, in bytes, for which the import will be in
synchronous mode. Files above this size will be imported
in asynchronous mode.
Default: 20480
PDFExportMaxRecords Maximum number of report rows to be exported to a PDF.
Default: 1500
TabularReportLayeringLimit The maximum number of layers allowed in a tabular report.
Defaults to 7.
MaxLoopItems You can configure this field value for "Max number of
records to iterate through in a loop for Templates and
Reports".
Default: 10000 records.
Note: Setting a very high value may affect the
template/report processing at the backend. So, the value
for this shared property should be carefully configured.
From the System Console > System > Shared Properties > Limits > Backup & Restore define, modify or
view the below properties.
Backup & Restore Property Description
MaxSystemBackups Max number of system backup files to keep per
customer. The system will delete older files if this
number is exceeded.
Default: 7
MaxBackupsPerMonth Maximum number of times a backup activity can be
performed by a customer tenant per month. For
information on using this property, see Backup and
restore on page 730.
Default: 10
StorageUsageLimitForBkp Storage usage limit (in MB) of a full backup. For
information on using this property, see Backup and
restore on page 730. Default:20
From the System Console > System > Shared Properties > Limits > Triggers define, modify or view the
below properties.
Triggers Property Description
MaxDelayedTriggers Maximum number of triggers to be executed for
delayed updates
Default: 20
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 805
Chapter 13: Installing and administering Private Cloud
Triggers Property Description
MaxJSTimeMs Maximum elapsed time for the server-side JavaScript
formula engine per formula in ms (formula will be
aborted afterwards).
Default: 3000
MaxRecurrEvents Maximum number of recurrent calendar events
Default: 300
MaxRuntimeTriggers Maximum number of triggers to be executed for
non-delayed updates.
Default: 100
MaxTimeToRunTrigMS Maximum time to run a group of triggers
ON_AFTER_UPDATE etc.
Default: 30000 (30 seconds)
MinRecursType Minimum allowed recursion interval for triggers and
batch jobs:
• 1: day (24 hours)
• 4: hour
• 5: minute 1
Default: 1
From the System Console > System > Shared Properties > Limits > HTTP Client define, modify or view
the below properties.
HTTP Client Property Description
HTTPConnectTimeOut The default socket timeout in milliseconds which is the
timeout for waiting for data in a given request. A
timeout value of zero is interpreted as an infinite
timeout. Default value 15 seconds.
HTTPReadTimeOut Specifies the length of the HTTP read timeout, in
milliseconds, in Rollbase triggers. If this property is not
present, its value is interpreted as 0, which means an
indefinite timeout value.
Default: 20000milliseconds
Note: This property is not applicable if you are running
Rollbase in Apache. You will have to directly configure
keep-alive settings in Apache.
InternalCommsHTTPTimeOut Defines the socket timeout in milliseconds, which is
the timeout for waiting for data or, put differently, a
maximum period inactivity between two consecutive
data packets in a socket. Default value 60 mins and
is applicable to Internal component communications.
InternalCommsMaxConnections Maximum number of client connections in the pool to
service connection requests from multiple execution
806 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Administration
HTTP Client Property Description
threads. Default value 2000 and is applicable to
Internal component communications.
InternalCommsMaxPerRoute Maximum number of client connections in the pool per
route to service connection requests from multiple
execution threads.
This is a restartable shared property to configure as
necessary.
Default value 200 and is applicable to Internal
component communications.
ProxyCommsMaxConnections Maximum number of client connections in the pool to
service connection requests from multiple execution
threads.
This is a restartable shared property to configure as
necessary.
Default value 200and is applicable to REST, SOAP,
WSDL & JSDO servlet communications.
ProxyCommsMaxPerRoute Maximum number of client connections in the pool per
route to service connection requests from multiple
execution threads.
This is a restartable shared property to configure as
necessary.
Default value 100 and is applicable to REST, SOAP,
WSDL & JSDO servlet communications.
ProxyCommsHTTPTimeOut Defines the socket timeout in milliseconds, which is
the timeout for waiting for data or, put differently, a
maximum period inactivity between two consecutive
data packets in a socket.
This is a restartable shared property to configure as
necessary.
Default value 60 mins and is applicable to REST,
SOAP, WSDL & JSDO servlet communications.
From the System Console > System > Shared Properties > Limits > Database define, modify or view the
below properties.
Database Property Description
D2C_ConnIdleTimeInMins Specifies the duration in minutes until which an existing
DataDirect Cloud connection can stay idle. If a
connection is found idle for the specified duration, a
new connection is created and used.The property takes
values between one to five.
• Minimum value: 1
• Maximum value:5
Default: 3
D2C_ConnPoolSize Specifies the number of connections to be cached and
reused in order to avoid creating new connections to
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 807
Chapter 13: Installing and administering Private Cloud
Database Property Description
the datasources in DataDirect Cloud (D2C) frequently.
The property takes values between two to ten.
• Minimum value: 2
• Maximum value:10
Default: 5
MaxAlarmConnections The system will send a message to admin if number
of database connections exceeds this value
Default: 90
MaxConnections Maximum number of database connections in each
connection pool.
Default: 100
MinConnections Number of database connections initially created in
each connection pool.
Default: 1
MaxNotUsedConnTimeMins Maximum time (in minutes) allowed database
connection in a pool to be idle. The connection will be
closed after that amount of time has elapsed.
Default: 30
MaxInUseConnTimeMins Maximum time (in minutes) allowed for a database
connection to be in use. The connection will be forced
to close after the amount of time elapses..
Default: 30
MaxConnLifetimeMins Maximum connection lifetime before closure (in
minutes)
Default: 60
MaxTransactionTime Maximum time in minutes to allow a database
transaction to run (will be rolled back after that)
Default: 10
MaxIntgFields Maximum number of BIGINT fields.
Default: 15
MaxStrFields Maximum number of VARCHAR(100) fields (in MySQL
notation).
Default: 200
MaxDateFields Maximum number of DATETIME fields.
Default: 50
MaxDblFields Maximum number of DECIMAL(20,8) fields
Default: 50
MaxTxtFields Maximum number of LONGTEXT fields
Default: 50
808 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Administration
Database Property Description
MaxDbLongStrLength Maximum size (in chars) of long text fields (CLOBs)
to be stored in the database
Default: 80000 Maximum Value: 180000
From the System Console > System > Shared Properties > Limits > Email define, modify or view the below
properties.
Email Property Description
MaxAttachmentSizeKB Maximum size of email attachment in KB
Default: 2048
MaxEmailAttachments Maximum number of email attachments.
Default: 3
MaxEmailBodyKB Maximum size of email message body in KB
Default: 2048
From Administration > Setup Home > Administration Setup > Authentication > Authentication Type >
Password > Next define, modify or view the below Master Tenant Authentication properties.
Master Tenant Authentication Property Description
SecurityLevel Specifies the security level for the master tenant. See
Setting and changing security levels on page 845 for more
information about security levels.
Default: 1
ExpirationPolicy The number of days after which a user's password expires
on the master tenant. You can leave this setting blank if
you want to keep the password from expiry.
Default: 0
From Administration > Setup Home > Administration Setup > Account Settings define, modify or view
the below Master Tenant properties.
Master Tenant Property Description
AdditionalLangCode Specifies a list of comma-separated language codes (based on ISO
631-1) for the Rollbase Master tenant. Setting this property ensures
that the Master tenant supports full language translation to the
additional language from the default base language (English). For
more information about language support, refer Language support
on page 740.
Default: None (must be specified prior to server start up)
MasterCloudStorageType Indicates the cloud storage type for master Tenant such as - Progress
Rollbase Storage, Amazon S3 or Microsoft Azure. As an alternative
to local storage, you (an ISV or a Private Cloud user) can purchase
and enable a third-party cloud storage (Amazon S3 or Microsoft
Azure) for your customer tenants. Cloud storage is used on a tenant
by tenant basis
Default: String.valueOf(ICloudConst.CLOUD_ROLLBASE
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 809
Chapter 13: Installing and administering Private Cloud
Master Tenant Property Description
MasterCloudStorageDir The S3 bucket to use for this customer tenant.For Microsoft Azure,
this will be empty.
Default: Null
MasterCloudStorageUser The Access Key ID assigned to your AWS account or the name of
your Azure account.
Default: Null
MasterCloudStoragePassword The Secret Access Key associated with the Access Key ID for AWS
or the Account Key for your Azure account.
Default: Null
From System Console > Monitoring > Diagnostics > Debug define, modify or view the below properties.
Debug Property Description
ShowDebugInfo Set this flag to true if you use the server for
development work only. This will eliminate the waiting
time when deleting applications and objects.
Default: false
From System Console > System > Control Panel > Configuration > Email define, modify or view the below
properties.
Email Property Description
MailHost Selects the mailing option to be provided at instance
level:
• SMTP: Provide a valid SMTP host name, for
example, smtp.gmail.com, to select SMTP as
the default mailing option.
• Exchange: A value of Exchange selects Exchange
as the default mailing option.
• Gmail: A value of Gmail selects Gmail as the
default mailing option.
Default: Null
MailPort The port used to access the mail server. This property
is only valid for SMTP. The value will be ignored for
Exchange and Gmail.
Default: 25
MailUseSSL Specifies the use of SSL or TLS encryption to access
mail server. This property is only valid for SMTP. The
value will be ignored for Exchange and Gmail. You
can set this property to:
• true or 1: If your mail server uses Secure Socket
Layer (SSL) encryption.
• false or 0: If your mail server uses no encryption.
810 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Administration
Email Property Description
• 2: If your mail server uses Transport Layer Security
(TLS) encryption.
Default: false or 0
MailUser The email address used for outgoing emails. This
property is only valid for SMTP and Exchange. The
value will be ignored for Gmail.
Default: NullCopied from AdminEmail, which is
required.
MailPassword The password for the mail user account. This property
is only valid for SMTP and Exchange. The value will
be ignored for Gmail.
Default: Null
From System Console > System > Control Panel > Authentication define, modify or view the below properties.
Authentication - General Properties Description
AuthOverrideAtCustomer When true, each tenant can configure an
authentication method using the Authentication setup
page. When false, all tenants share a global
(Rollbase instance level) authentication method
configured in the shared.properties file. Defaults
to true. Currently, only Kerberos and SAML/ADFS
authentication can be configured at the instance level.
DefaultAuthType When configuring the instance-level authentication
method, the authentication type. Can be set to true
or false. Valid values are SAML and Kerberos.
Default:
ISecurityConstants.AUTH_PASSWORD_STR
See Configuring SAML/ADFS Authentication on page
857 and Configuring Kerberos Authentication on page
856 for more information.
APIAuth The authentication mechanism to user for login APIs.
The value supported for this property depends on the
authentication type:
• Password: Password, API Token, or Custom
• LDAP: LDAP, API Token, or Custom
• LDAP Advanced: LDAPTREE, API Token, or
Custom
• HTTP POST: HTTP POST, API Token, or Custom
• HTTP GET: AUTH REST, API Token, or Custom
• OpenEdge: OE
• Kerberos: API Token or Custom
• SAML: API Token, or Custom
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 811
Chapter 13: Installing and administering Private Cloud
Authentication - General Properties Description
Default: Null
IsSingleUserMultiTenantEnabled Set to true to allow users to switch tenants. Only
applies when all tenants use the same authentication
mode such as SAML/ADFS or custom and when the
same email address is associated with user accounts
in more than one tenant.
Default: false
Authentication - Custom Property Description
CustomAuthClass Determines the restrictions based on the
implementation of the custom authentication method.
Default: null
Authentication - SAML Property Description
SPKeyStoreFile The name of the keystore for SAML/ADFS
authentication.
Default: Null
SPKeyStorePassword The keystore password.
Default: Null
SPKeyStoreAlias The keystore alias.
Default: Null
AssertionConsumerIndex The index of the URLs to be used in the SP metadata.
In general, multiple URLs are not supported by most
of the IdPs, so you can set this to the default of 0.
Default: 0
SPMetadataFile The name of the SP metadata file.
Default: Null
IdPId The entity ID of the Identity Provider. This is the value
of the entityID attribute of the EntityDescriptor
element in the IdP metadata file.
Default: Null
IdPMetadataFile The IdPmetadata file name.
Default: Null
SPId The entity ID of the service provider.This is the value
of the entityID attribute of the EntityDescriptor
element in the SP metadata file.
Default: Null
SAMLLogoutURL A custom URL that can be configured by the
SAML/ADFS master administrator to redirect the user
after logout.
Default: Null
812 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Administration
Authentication - SAML Property Description
AuthComparison A comparison attribute on the AuthnContext request
parameter to indicate how an authentication context
should be evaluated. The authentication context will
be evaluated based on the relative strengths of the
authentication context classes specified in the
AuthnContext request and the authentication methods
offered by an IdP.
The four available comparison values are - better,
exact, maximum, and minimum. If no value is
specified, it will default to minimum .
See setAuthentication on page 1256 and
getAuthentication on page 1218 for more information.
Default: minimum
AttributeMap A pipe separated mapping of the attributes in the form
integration name in Rollbase=attribute name sent from
IdP. The Rollbase attribute loginName is required.
At least, two mapped attributes are required. For
example:
firstName=givenName|lastName=sn|loginName=uid|city=city
Default: Null
Authentication - Kerberos Property Description
KerberosPassword The Rollbase server should be part of the Active
Directory domain. Enable KerberosPassword=<AD
account password> (used for authentication).
Default: Null
KerberosUsername Enable KerberosUsername=<AD account
password> (used for authentication).
Default: Null
KerberosDebug Uncomment this property.
Default: false
KerberosDomainController Set KerberosDomainController=<Domain
Controller> (the Kerberos Ticket Issuing Server).
Default: Null
KerberosDomainName Set KerberosDomainName=<Windows Domain
Name>
Default: Null
From System Console > System > Control Panel > Google Integration define, modify or view the below
properties.
Google Integration Property Description
GoogleClientId The client ID required for accessing enabled Google
applications. See Enabling Google Apps for Rollbase
Private Cloud on page 753 for information about
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 813
Chapter 13: Installing and administering Private Cloud
Google Integration Property Description
obtaining the client ID. You can set this to true or
false.
Default: None
GoogleClientSecretKey The secret key required for accessing enabled Google
applications. See Enabling Google Apps for Rollbase
Private Cloud on page 753 for information about
obtaining the secret key. You can set this to true or
false.
Default: None
GoogleApplicationName Google Application name to access Google Calendar
and Docs (Spreadsheets), preferably have the format
[company-id]-[app-name]-[app-version]
Default: {!SystemName}- {!SystemName}-1
GoogleUserName The Gmail email address, for example,
[email protected]. The value will be ignored for
SMTP and Exchange. You can set this to true or
false.
Default: None
GoogleRefreshToken Used to provide a refresh token for Gmail email
settings. The token can be obtained by using Google
auth. The value will be ignored for SMTP and
Exchange. You can set this to true or false.
Default: None
Control Panel
The table below lists all available Control Panel properties and its default values.
Access the Control Panel tab from the Application Switcher > System Console > System.
Configure the values as needed and Save.
License and Usage Description
License ID You can view and update your Rollbase license ID
here.
Host Name The port or URL on which your Rollbase instance is
hosted.
Edition The Rollbase edition. For example: Cluster Server.
Expiration Date Date of expiry for the Rollbase license.
Max Users Indicates the maximum number of users that can use
the Rollbase instance.
Max Servers The maximum number of simultaneous user
connections that are allowed on an instance of SQL
Server.
814 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Administration
License and Usage Description
Total Users Total number of users that are allowed to use the
Rollbase instance. Click the Refresh icon to view
updated value.
Total Servers Total number of servers that are being used by the
Rollbase instance.
Usage Report Description
Reporting Date Select the month for which you want to generate the
usage report.
Anonymise Tenant Select this option to keep the tenant information
anonymous.
Download Downloads the system usage report as a .csv file with
tenant name such as the date of tenant creation,
number of users and Admin Users for each tenant.
Re-index/Re-Create Lucene Index For Description
Master Zone Select this checkbox to enable the Lucene Index
re-creation for the Master Zone.
Customers Select all customers or specific customers from the
search results.
Reindex Click this button to start the re-indexing process.
From System Console > System > Control Panel > Configuration > Email define, modify or view the below
properties.
Email Property Description
Host Name Selects the mailing option to be provided at instance
level:
• SMTP: Provide a valid SMTP host name, for
example, smtp.gmail.com, to select SMTP as
the default mailing option.
• Exchange: A value of Exchange selects Exchange
as the default mailing option.
• Gmail: A value of Gmail selects Gmail as the
default mailing option.
Default: Null
SMTP > Port Number The port used to access the mail server. This property
is only valid for SMTP. The value will be ignored for
Exchange and Gmail.
Default: 25
SMTP > Encryption Specifies the use of SSL or TLS encryption to access
mail server. This property is only valid for SMTP. The
value will be ignored for Exchange and Gmail. You
can set this property to:
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 815
Chapter 13: Installing and administering Private Cloud
Email Property Description
• true or 1: If your mail server uses Secure Socket
Layer (SSL) encryption.
• false or 0: If your mail server uses no encryption.
• 2: If your mail server uses Transport Layer Security
(TLS) encryption.
Default: false or 0
User Name/ Email Address The email address used for outgoing emails. This
property is only valid for SMTP and Exchange. The
value will be ignored for Gmail.
Default: NullCopied from AdminEmail, which is
required.
Password The password for the mail user account. This property
is only valid for SMTP and Exchange. The value will
be ignored for Gmail.
Default: Null
From System Console > System > Control Panel > Configuration > Authentication define, modify or view
the below properties.
Authentication - General Properties Description
Authentication Mode When true, each tenant can configure an
authentication method using the Authentication setup
page. When false, all tenants share a global
(Rollbase instance level) authentication method
configured in the shared.properties file. Defaults
to true. Currently, only Kerberos and SAML/ADFS
authentication can be configured at the instance level.
UI Authentication When configuring the instance-level authentication
method, the authentication type. Can be set to true
or false. Valid values are SAML and Kerberos.
Default:
ISecurityConstants.AUTH_PASSWORD_STR
See Configuring SAML/ADFS Authentication on page
857 and Configuring Kerberos Authentication on page
856 for more information.
API Authentication The authentication mechanism to user for login APIs.
The value supported for this property depends on the
authentication type:
• Password: Password, API Token, or Custom
• LDAP: LDAP, API Token, or Custom
• LDAP Advanced: LDAPTREE, API Token, or
Custom
• HTTP POST: HTTP POST, API Token, or Custom
816 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Administration
Authentication - General Properties Description
• HTTP GET: AUTH REST, API Token, or Custom
• OpenEdge: OE
• Kerberos: API Token or Custom
• SAML: API Token, or Custom
Default: Null
Enable Single User Multi Tenant Set to true or selecting the checkbox will allow users
to switch tenants. Only applies when all tenants use
the same authentication mode such as SAML/ADFS
or custom and when the same email address is
associated with user accounts in more than one tenant.
Default: false
Configuration > SAML/ADFS SP Configuration Description
SPKey Store File The name of the keystore for SAML/ADFS
authentication.
Default: Null
SPKey Store Password The keystore password.
Default: Null
SPKey Store Alias The keystore alias.
Default: Null
Assertion Consumer Index The index of the URLs to be used in the SP metadata.
In general, multiple URLs are not supported by most
of the IdPs, so you can set this to the default of 0.
Default: 0
SP Metadata File The name of the SP metadata file. Select the needed
file.
Default: Null
Issuer (IDP/ADFS Entity ID) The entity ID of the Identity Provider. This is the value
of the entityID attribute of the EntityDescriptor
element in the IdP metadata file.
Default: Null
Identity Provider/ADFS Metadata The IdPmetadata file name.
Default: Null
Service provider/Relying Party Entity ID The entity ID of the service provider.This is the value
of the entityID attribute of the EntityDescriptor
element in the SP metadata file.
Default: Null
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 817
Chapter 13: Installing and administering Private Cloud
Configuration > SAML/ADFS SP Configuration Description
Identity Provider Logout URL A custom URL that can be configured by the
SAML/ADFS master administrator to redirect the user
after logout.
Default: Null
Authentication Context Comparison Type A comparison attribute on the AuthnContext request
parameter to indicate how an authentication context
should be evaluated. The authentication context will
be evaluated based on the relative strengths of the
authentication context classes specified in the
AuthnContext request and the authentication methods
offered by an IdP.
The four available comparison values are - better,
exact, maximum, and minimum. If no value is
specified, it will default to minimum .
See setAuthentication on page 1256 and
getAuthentication on page 1218 for more information.
Default: minimum
Attribute Map Mapping of the attributes in the form integration name
in Rollbase=attribute name sent from IdP. The Rollbase
attribute loginName is required. At least, two mapped
attributes are required.
Default: Null
Custom Authentication Description
Custom Authentication Determines the restrictions based on the
implementation of the custom authentication method.
Default: null
Kerberos Configuration Description
Kerberos UserName Enable KerberosUsername=<AD account
password> (used for authentication). Enter the
Kerberos User Name.
Default: Null
Kerberos Password The Rollbase server should be part of the Active
Directory domain. Enable KerberosPassword=<AD
account password> (used for authentication). Enter
the Kerberos password.
Default: Null
Kerberos Domain Name Set KerberosDomainName=<Windows Domain
Name>
Default: Null
Kerberos Domain Controller Set KerberosDomainController=<Domain
Controller> (the Kerberos Ticket Issuing Server).
Default: Null
818 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Administration
Kerberos Configuration Description
JAAS Configuration Configure different login modules for the Rollbase
application without changing any code.
Kerberos Debug Select the checkbox as needed.
Default: false
From System Console > System > Control Panel > Configuration > Google Integration define, modify or
view the below properties.
Google Integration Property Description
Client Id The client ID required for accessing enabled Google
applications. See Enabling Google Apps for Rollbase
Private Cloud on page 753 for information about
obtaining the client ID. You can set this to true or
false.
Default: None
Client Secret Key The secret key required for accessing enabled Google
applications. See Enabling Google Apps for Rollbase
Private Cloud on page 753 for information about
obtaining the secret key. You can set this to true or
false.
Default: None
Application Name Google Application name to access Google Calendar
and Docs (Spreadsheets), preferably have the format
[company-id]-[app-name]-[app-version]
Default: {!SystemName}- {!SystemName}-1
Google User Name The Gmail email address, for example,
[email protected]. The value will be ignored for
SMTP and Exchange. You can set this to true or
false.
Default: None
Google Refresh Token Used to provide a refresh token for Gmail email
settings. The token can be obtained by using Google
auth. The value will be ignored for SMTP and
Exchange. You can set this to true or false.
Default: None
From System Console > System > Control Panel > Configuration > Field Groups define, modify or view
the XML as needed.
Note:
If you create or update any field group, you may need to update language resource files. Updated language
resource files will have effect after server restart. Experienced Private Cloud administrators can add their own
object attributes here.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 819
Chapter 13: Installing and administering Private Cloud
Field Group Property Description
groupName The table or group name for a group of fields. You can
modify or edit this in the Field Groups XML.
columnName The column name for a group of records. You can
modify or edit this in the Field Groups XML.
fieldName The field name. You can modify or edit this in the Field
Groups XML.
From System Console > System> Control Panel > Configuration > List Items define, modify or view the
XML as needed.
Note:
This section contains a list of shared pick list Items (countries, states, etc.) to be added to each tenant during
customer creation. You can modify this file.
From System Console > System > Control Panel > Configuration > Legacy Objects view the XML as
needed.
Note:
We recommend that you do not modify this file.
From System Console > System > Control Panel > Configuration > Security Level define, modify or view
the XML as needed.
Note:
You can modify this file and change the default levels or add more levels according to your security needs.
From System Console > System > Control Panel > Configuration > Service Level define, modify or view
the license levels in the XML as needed.
Note:
You can modify this file to change default levels or to add more levels according to your business needs.
From System Console > System > Control Panel > Configuration > Default Cards define, modify or view
the in the XML as needed.
Note:
You can modify this file to change default cards that renders in tablets and phones. Card Template content
should be HTML encoded.
Monitoring
The table below lists all available Monitoring properties and its default values.
Access the Montoring tab from the Application Switcher > System Console > System.
Configure the values as applicable and Save.
820 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Administration
Jobs and Events Description
Jobs You can view and sort all queued Import Jobs, System
Jobs and Batch Jobs for a customer by Job in Queue,
Job Type, Status, and Database. Click Log to view
the log details.
Events Displays the system events by Database Name, Email
Queue and Delayed Trigger. Click Email Logsto view
the email logs and click Event Logs to view the event
logs. Click the Refresh icon to refresh the page
information.
Search Jobs Displays the search jobs by Customer, Job in Queue,
Created At and Component. Click Log to view the jobs
log. Click the Refresh icon to refresh the page
information.
System Logs Description
All Customers Logs You can view and sort all queued Import Jobs, System
Jobs and Batch Jobs for a customer by Job in Queue,
Job Type, Status, and Database. Click Logto view the
log details.
Master Server Logs Displays the Master Server logs by File Name, Last
Updated and File Size. Click the Refresh icon to
refresh the page information.
App Server Logs Displays the App Server logs by File Name, Last
Updated and File Size. Click the Refresh icon to
refresh the page information.
NGINX Server Logs Displays the NGINX Server logs by File Name, Last
Updated and File Size. Click the Refresh icon to
refresh the page information.
Audit Trail Description
Activity Trail Displays the activity performed on the system by
Action, Date/Time, Content, User and Login User. Click
the Refresh icon to refresh the page information.
Update History Displays the Master Server logs by File Name, Last
Updated and File Size. Click the Refresh icon to
refresh the page information.
Define, modify or view the below Diagnostic properties and Save.
Debug Property Description
Show Debug Info Set this flag to true if you use the server for
development work only. This will eliminate the waiting
time when deleting applications and objects.
Default: false
Object to Trace View SQL Queries Enter Object Definition ID. Views and Reports involving
that ID will be logged in customer's log file named
query.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 821
Chapter 13: Installing and administering Private Cloud
Debug Property Description
Customer Zone to Trace ALL SQL Queries Enter the following information and Submit it.
• Enter Customer ID to debug SQL queries. Use log
file named query.log for debugging.
• Enter Customer ID to debug search indexing. Use
log file named search.log for debugging.
Diagnostics Description
System Tests Displays the various system tests executed by Status,
System Test, Context and Response Text.
PD4ML Configure, view/hide the PD4ML font property location,
content, and TTF files .
Rollbase configures the PD4ML font properties during
server initialization.
As part of the configuration procedure, it will search
for the pd4fonts.properties file in the
rollbase_home/config folder. See Configuring
PD4ML for detailed information.
After adding new fonts to a machine, click Reconfigure
to reconfigure the PD4ML TTFsettings on the server.
This action will re-generate/generate the PD4ML fonts
properties file to be used for PD4ML TTF embedding
such that the PD4ML new font additions can be fixed
without system restart .
Cache Stats You can view Master cache attributes and information
and sort it by Cache Instance, Name, and Type. Click
the Refresh icon to refresh the page information.
822 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Administration
Managing customer tenants
A customer tenant is a separate virtual space for Rollbase applications. For Rollbase private cloud, master
tenant administrators create and manage customer tenants using the System Console application:
To create a customer tenant, you create a Customer record. The Customer record specifies configuration
such as which applications users of that customer tenant can access, where their data will be stored, and the
level of security. From the Customer record, master tenant administrators can log into the customer tenant
with super-admin privileges (when this functionality is enabled). Some fields of Customer records, like the
address, can be edited by administrative users of the customer tenant through their Account Setting page.
The isActive formula field determines whether users can log in to the customer tenant. The default
implementation for the IsActive formula sets the Status of newly created customer records to Active. You
can change this formula if desired.
The Subscribers tab of the System Console application lists all users in all customer tenants. You cannot
create these records directly. Rollbase creates them when an administrator in the customer tenant creates a
User record. Subscriber records are useful for marketing, communication and other purposes such as sending
mass emails.
If you delete a Customer record, all records and hosted files from that tenant will be deleted. Deletion cannot
be reversed unless you have a backup file. You can restore customer data from a backup file created on a
different Rollbase server, see Moving and restoring customer tenants on page 828.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 823
Chapter 13: Installing and administering Private Cloud
Installing applications in new tenants automatically
The Customer record allows you to specify a list of applications that Rollbase installs when it creates the new
customer tenant. The Rollbase application is required, and Rollbase installs the applications you specify, in
order. When an application includes a Post Customer Create Script, that script is executed after the application
is installed. You can use a Post Customer Create Script to create a tenant with no administrative users, and
instead create a custom role that has some administrative permissions. See Creating a tenant with no
administrative users on page 825 for details.
Sometimes multiple applications contain the same component with different definitions. By default, Rollbase
accepts additions to component definitions, such as a new object field, but rejects conflicting changes, such
as those to an existing field name.
The AppInstallOverridesChanges property in the Shared Properties controls this behavior. If the
property value is true, and Rollbase installs an application with a conflicting component definition, it accepts
it. As Rollbase installs applications, all conflicting component definitions override existing definitions.
For example, suppose a Contact application includes the User object, which is also part of the Rollbase
application. A developer makes two changes to the User object: a field addition, favoriteTeam; and a field
name change, lastName to familyName. An administrator adds the Contact application to the list of applications
to be installed in a new tenant and creates a new customer tenant. The Rollbase application always installs
first. The AppInstallOverridesChanges property value determines what happens to the User object when
the Contact application is installed:
• With the default value, false, Rollbase adds the new favoriteTeam field to the User object.
• With a value of true, Rollbase adds the new favoriteTeam field and changes the lastName field's name
to familyName.
Creating a new customer record
A Customer record defines the applications, security level, storage information and usage for an organization
or group that will be using a customer tenant.
Follow these steps to create a new Customer record.
1. Log in to the Private Cloud master tenant as an administrator.
2. From the application switcher, select System Console.
3. Select the Customers tab.
4. In the Customers List section, click New Customer.
5. Enter the following information:
• Database — select the database to hold this customer's data.
• Plan — select a pricing plan to determine default limits on the number of records, fields and other
resources allowed for this customer. See System Console > System > Control Panel > Configuration
> Service Levels for information on how to customize these plans.
• Security Level — select the security level for the customer tenant. The customer can later change this
from their Account Settings page.
• Applications — select the applications to be installed into the new customer tenant. If this field does
not appear on the New Customer page, click Design This Page and drag Applications Lookup onto
the page from the Available Components list. The Rollbase application will be included by default. It
is required, do not remove it. For more information, see Installing applications in new tenants automatically.
• Email — specify the email address for the first administrative user for this customer tenant. If you do
not want the first user to have the Administrator role, you can change that user's role and create a
customer tenant with no administrators. See Creating a tenant with no administrative users on page 825
for details.
824 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Administration
• Storage server — if more than one storage server is installed, select the storage server assigned to
this customer.
• Search server — if more than one search server is installed, select the search server assigned to this
customer.
6. Click Save to create the record, or click Save and New to save the record and create another Customer
record.
After several seconds or minutes (depending on the speed of your server) the system will finish the tenant
creation process by installing all selected applications. Until tenant creation is completed, the Login button on
the Customer view page is disabled. The page will be refreshed automatically when process is completed and
the button will be enabled. After this is finished, Rollbase sends a welcome email to the first administrative
user, who will then be able to log in to the new tenant. When an administrator of the master tenant logs in to
a customer tenant, they have super-admin privileges.
Creating a tenant with no administrative users
You can create a customer tenant with no administrative users and assign certain administrative permissions
to non-administrative roles. While administrators on the master tenant can log into the tenant to perform
administrative tasks, users with non-administrative roles can perform most day-to-day tasks.
Follow these steps to create a tenant with no administrative users:
1. Set the value of the shared property AllowAdminLessTenant to true. See Shared Properties on page
786 for details.
2. Create a custom role and assign it some administrative permissions, such as Manage Users and Manage
Roles. See Roles and permissions on page 648 for a list of administrative permissions you can grant to a
non-administrative roles.
Note: Ensure that the created role is associated with an Integration Code.
3. Select at least one application to be installed during customer creation and attach the role to the application.
For that application, create a Post Customer Create Script that changes the role of the first user from
Administrator to the role you created and attached. For example:
var objId = rbv_api.selectNumber("SELECT id FROM USER where role =90");
var role = rbv_api.stringToJson(rbv_api.getRoleById("868114"));
rbv_api.setFieldValue("USER",objId,"role",role.code);
See Post install scripts on page 127 for more information.
4. Follow the steps in Creating a new customer record on page 824 to create the customer tenant, selecting
the application with the Post Customer Create Script to be installed during customer creation.
The user whose email you enter when creating the customer will now have the custom role instead of the
Administrator role.
Working with customer records
To view and work with Customer record details, Rollbase administrators of the master tenant can do the
following:
1. From the application switcher, select System Console:
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 825
Chapter 13: Installing and administering Private Cloud
2. Select the Customers tab.
3. In the Customers List area, click the Customer Name.
4. Do any of the following operations:
• View Logs: View log files associated with this customer, which can be useful for troubleshooting and
debugging. Requires view permission
• Login: Log into a customer tenant as a Super-Admin (invisible user with full access). This option requires
log in permission. The button only appears after the administrative user of the customer tenant enables
access for the master tenant users. For more information about enabling support access, see Enabling
an administrative user to log into a customer tenant on page 683.
• Edit: Modify the customer record. Requires edit permission.
From the More Actions drop-down menu, do any of the following:
• Delete: Deletes the customer record and all customer's data. Requires delete permission.
• Convert: Converts the customer into another object.
• Clone: Clones the selected customer information to quickly create a new customer.
Note: Email and Login Name of the First Administrative User details cannot be same as that of the
existing customer.
• Send: To send email notifications using a selected template with attachments to selected users, as
required.
• Reindex: To update and reindex all free text queries for search for the customer.
• Sync Subscribers: Updates the subscriber information for the customer.
826 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Administration
• Login As: Log into a customer tenant as a particular user. This option requires log in permission. The
button only appears after the administrative user of the customer tenant enables access for the master
tenant users. For more information about enabling support access, see Enabling an administrative user
to log into a customer tenant on page 683.
• Data Maintenance: Use this procedure to restore the integrity of relationships for this customer. This is
only for fixing problems and will not be used under normal conditions.
• System Backup & Restore: Monitor and create system backup files created in this customer. See
Backup and restore on page 730 for more information.Restore from backup: (from Backup page) Use
the Restore option to delete all current customer data and replace it with data imported from the selected
backup file (no users can be logged in during backup).
• Storage Move:Select this option to move the customer storage from cloud-cloud, local-cloud, or
cloud-local. Then, select a storage option from the New Storage drop-down list, enter the required
storage details and click Move.
• Database Move: Moves customer data to another (selected) database. Requires edit permission.
Additionally, after performing Database Move, you must navigate to the customer's details page, under
Runtime Information area, select Load to load the customer tenant from the production server cache.
Note: You unload and load the customer tenant for the new settings to take effect. Only after loading
the customer tenant from the production server cache can the users log into the customer tenant.
• Set Preferences: Enables selecting parser preferences for DOC, PDF, and DOCX documents. Then,
select the parser preferences for DOC, PDF, and DOCX type of documents.
• PDF Parser: Default, Aspose Parser and Built-In Parser are the available options. If you want to
make Aspose Parser as the Default option, you must select the IsAsposePDFParserEnabled
shared property. By default, this property is unchecked. See Shared Properties on page 786 for more
information.
• Doc Parser: Default, Aspose Parser and Built-In Parser are the available options. If you want to
make Aspose Parser as the Default option, you must select the IsAsposeDocParserEnabled
shared property. By default, this property is unchecked. See Shared Properties on page 786 for more
information.
Note: To use the existing RTF documents, you must ensure that the Aspose Word jar is present in
the lib folder.
• Docx Parser: Default, Aspose Parser and Built-In Parser are the available options. If you want to
make Aspose Parser as the Default option, you must select the IsAsposeDocxParserEnabled
shared property. By default, this property is unchecked. See Shared Properties on page 786 for more
information.
Note: If Aspose PDF and Word jars are not present in the lib folder, the Built-In Parser will be used
by default and the PDF Parser, Doc Parser and Docx Parser drop-down lists will not be visible.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 827
Chapter 13: Installing and administering Private Cloud
Moving and restoring customer tenants
You can move customer data for a customer tenant from one Rollbase Private Cloud installation to another for
backup and restoration. The restoration process will create database records from information stored in the
backup file using unique IDs created on the originating server. These IDs may potentially conflict with IDs
already present in destination database on the target server. Therefore, Progress recommends that you use
a fresh empty database to restore customer tenant data created on another server.
It is important to note that although moving customer data between servers is technically possible, the following
procedure may be error prone and may impose additional limitations.
1. Create and download a backup of the customer on the source server (see Working with customer records
on page 825).
2. Create and register a new empty database (see Adding a new database for use with customer tenants on
page 832).
3. Create a New Customer on the target server assigning the newly created empty database to it (see Creating
a new customer record on page 824).
4. Copy the backup file from the source server to the target server or upload the downloaded backup file on
your target server. You will find the destination location on the system backup page. For information on
navigating to the system backup page and uploading the system backup, see Working with customer records
on page 825.
After copying or uploading the customer backup, your backup will be listed in your Backup page:
5. Select the Restore link to start the restoration process.
828 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Administration
Note: If the original customer tenant has lots of data in uploaded files, the backup file will not include these
files. In this case, you must move your uploaded files into your cloud storage or copy those files manually
from the original server to the target server.
When the process is complete, you will receive a confirmation email from Progress Rollbase. Note that you
can check the backup.log file on your customer for information about the restoration process and possible
errors.
Enabling logging for charts and views
Administrators of the master tenant can enable logging to debug charts and views for a customer tenant. The
log will contain SQL statements and results to help with troubleshooting.
Note: Logging is limited to only one chart or view at a time. If logging is enabled one one chart or view, and
you enable logging on a second chart or view, the setting on the first one is automatically disabled.
To enable logging for a chart or view, follow these steps:
1. Navigate to the customer record for the tenant and click Login.
2. In the customer tenant, navigate to the object definition that contains the chart or view.
3. Navigate to the Charts or Views section.
4. Click Edit next to the chart or view.
The Edit page opens:
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 829
Chapter 13: Installing and administering Private Cloud
5. Scroll down to the Debug section:
6. Select the check box Log all SQL queries created by this <View or Chart> in query.log.
7. Click Save.
After exercising the view or chart, for example, by creating a new record, return to the edit page where you
enabled logging and click query.log to open the log file.
830 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Administration
Maintaining customer data
You can fix data integrity issues pertaining to relationship and data records, cleanup orphan relationship entries
of customer tenants and recalculate all the expression fields.
Note: Ensure you take a backup of your database before you run this utility.
Follow these steps to maintain customer data:
1. Navigate to the required customer tenant.
2. In the customer tenant, navigate to the More Options menu.
3. Select Data Maintenance. The Data Maintenance page opens.
4. Choose the data maintenance operation/s you want to run.
• Fix relationship field for data records with M:1 and 1:1 cardinality — This operation fixes data
integrity issues pertaining to relationship and data records of the customer. This option is selected by
default.
• Cleanup orphan relationship records — This operation cleans up relationship entries from:
• RB_RELATIONSHIP table that does not have a valid relationship definition.
• RB_RELATIONSHIP table that does not have a valid object definition.
• RB_RELATIONSHIP table that is invalid.
For every relationship record in RB_RELATIONSHIP table, invalid entries are determined by checking
the data tables RB_CUST_DATA, RB_USER_DATA, RB_OBJ_DATA, and RB_DELETED_OBJS.
This operation is done in batches as RB_RELATIONSHIP table may contain lots of relationship records.
• Recalculate all Expression Fields — This operation recalculates all expression field for all data records
from its object definition present on the customer tenant.
Note: To exhaustively capture operations run on a tenant, two new tenant level logs
dataMaintenance.log and dataMaintenance_deletedRels.log are added. The latter captures
only the details of what has been deleted.
5. Click Submit to initiate the data maintenance job. A success message is displayed for the same.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 831
Chapter 13: Installing and administering Private Cloud
Managing databases
Thenode-config.json file in the config directory of the Rollbase Master Server instance specifies
configuration for the database(s) used by Rollbase. The configuration includes connection information determines
which database will store data for a particular customer tenant. If you change the file manually, you must restart
the Web server. An administrator logged into the master tenant can create and update system databases from
the System Console > System > Databases without restarting the Web server.
The topics in this section cover the following procedures:
• Adding a new database for use with customer tenants on page 832
• Creating custom database indexes on page 834
• Adding columns to a Private Cloud database on page 835
Adding a new database for use with customer tenants
Before adding a database in Rollbase Private Cloud, you must first install it in a location accessible from the
machine on which you will install Rollbase and then create Rollbase tables using the steps described in the
Installation section under Databases. Additionally, you must ensure that your Web server library has the required
JDBC driver. For example, for a PAS installed in the default location, it is the
Progress\Rollbase\Pas_Instance\common\lib folder.
To add a database in Rollbase Private Cloud, do the following:
1. Log into the master tenant as an administrator.
2. From the application switcher, select System Console.
3. Locate the Databases list on the System tab and click Add.
The Create Database screen appears:
832 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Administration
4. Specify the following database information:
• Database Name — A unique name that only contains alphanumeric characters
• Database Type — The type of database being created
Rollbase supports OpenEdge, MySQL, Oracle, or SQL Server. For Oracle and SQL Server, you can
choose to use a DataDirect JDBC driver.
• Database URL — The database URL
On selecting the Database Type field, this field presents you with an example URL. Substitute your host
name and schema name in the URL, or if you are using a different driver, provide the URL to that driver.
• User Name and Password — The user name and password required for Rollbase to access the database
5. Click Test Database Connection.
If the test is successful, the Save button is enabled.
6. Optionally, select:
• Use this database as default for new Customers to make this database as the default database for
the newly created customer tenants.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 833
Chapter 13: Installing and administering Private Cloud
• This database includes External tables which can be mapped as system objects if your database
makes use of external tables that can be mapped to Rollbase Objects..
7. Specify the following connection pool options for this database:
• Pool Type — The type of JDBC connection pooling mechanism to implement for managing JDBC
connections. You can implement connection pooling with Rollbase or Tomcat.
Note: If you want to change the pool type for your database, you must restart the server for the changes
to take effect.
• Min Connections — The minimum number of connections in the pool
• Max Connections — The maximum number of connections in the pool
• Max Time In Use — The maximum time (in minutes) allowed for the database connection to be in use.
The connection is lost after the specified time has elapsed.
• Max Idle Time — The maximum time (in minutes) allowed for the database connection in a pool to be
idle. The connection is lost after the specified time has elapsed.
• Max Life Time — The maximum connection lifetime before closure (in minutes)
• New Connection Timeout — The time allowed for a new database connection to be established. The
connection is lost after the specified time, and you must retry connecting to your database.
• Transaction Isolation — The degree of locking that occurs when selecting data. Progress recommends
that you consult your database manual to set this property. Use the Default option if you are unsure
about this setting.
8. Click Save.
After saving the information you entered, the new database is displayed in the list. The node-config.json
file is automatically updated on all the servers in your Private Cloud without a Web server restart.
After creating and adding a database, you can click Edit to modify any database information. If you want to
change the pool type for your database, you must restart the server for the changes to take effect.
Creating custom database indexes
Experienced database administrators can create or modify indexes to tune performance. Database indexes
can improve application performance because they reduce the processing required for certain queries. Indexes
should be used only after analyzing which SQL queries in an application are slow because of a database
bottleneck.
Rollbase object records are stored in RB_OBJ_DATA table, which has more than 500 columns. Some of these
columns are already indexed to improve performance of SQL queries. You can identify the indexed columns
by searching the database creation scripts for lines including the CREATE INDEX command. For example:
CREATE INDEX RB_OBJ_DATA_I17 ON RB_OBJ_DATA(OBJ_DEF_ID, STR2);
It is neither practical nor possible to index all columns in the RB_OBJ_DATA table. It is best to concentrate on
columns with large numbers of records per object. Indexes can be created for single or multiple columns. For
example, if your application uses a field mapped to a STR10 column to sort and filter large amount of records,
you could create an index on that column. The following database command would create such an index:
CREATE INDEX RB_OBJ_DATA_CUST1 ON RB_OBJ_DATA(OBJ_DEF_ID, STR10);
834 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Administration
Adding columns to a Private Cloud database
There are limits on the number of fields you can create per object definition. For instance, you cannot create
more than 50 fields of Date or Date/Time type. Rollbase uses the single wide database table, RB_OBJ_DATA,
to store all object records. That table has 50 columns of DATETIME type (in MySQL terms) named from DATE0
to DATE49. When a new field is created, one of these columns is assigned to that field to store data. If you
are a Private Cloud customer and have full control over your database, you can increase limits on the number
of fields.
To add columns:
• Use an SQL script to create more columns of the selected type to the following tables:
• RB_OBJ_DATA (main data table)
• RB_DELETED_OBJS (records in Recycle Bin)
• RB_USER_DATA (Rollbase users)
• RB_CUST_DATA (customers)
• Make sure that the newly added columns follow the naming convention and use continuous numbering. For
instance, you may create ten new Date/Time columns named DATE50, DATE51 to DATE59
• Make sure these new columns are added to all databases.
• Add entries to Shared Properties to reflect the new limits on number of columns.
Property Description Default Value
MaxStrFields Maximum number of 200
VARCHAR(100) fields (in MySQL
notation)
MaxIntgFields Maximum number of BIGINT fields 150
MaxDblFields Maximum number of 50
DECIMAL(20,8) fields
MaxTxtFields Maximum number of LONGTEXT 50
fields
MaxDateFields Maximum number of DATETIME 50
fields
After server restart, you should be able to create more Date or Date/Time type fields per object definition.
Marketplace and Support Portal
Your Rollbase customers can publish their applications to the Marketplace. See Using the Progress Rollbase
Marketplace on page 692 for more information.
Publishing an application will create a Published Application record in the System Console. The administrator
of the master tenant manages this process by monitoring and updating Published Application records.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 835
Chapter 13: Installing and administering Private Cloud
Apart from the fields which can be selected by the publisher, as an administrator in the master tenant, you can
set the following fields:
• Check Is System only if this application explicitly includes the User object. Progress recommends that you
create your own system application that includes the User object (similar to the Rollbase application) and
publish it from a dedicated tenant.
• Check Approved to allow this application to be installed by any user browsing the Marketplace.
Your customers can send feedback and report issues through the Help > Support Tickets menu. This will
create a Support Request record in your master tenant Support Center application. You can use an existing
workflow, or create your own actions to process these requests.
Test drive
You can set up dedicated customer tenants to provide test drive functionality for a particular application. To do
that:
1. Publish the application to the Applications Directory or Marketplace and make it available using the
Publish button on the application view page. Note: publishing is only available for the original application
creator.
2. Publishing will create a record in Published Apps tab in the System Console. Edit that record and:
a. Check the Approved box.
b. Select the Customer where the published application was developed in the Test Drive lookup.
c. Verify that your published application appears on the Applications Directory or Marketplace portal.
3. Go back to the dedicated Customer and assign permissions for the Portal User user role. Progress
recommends that you assign complete permissions for the Test Drive application.
4. Create a set of records to demonstrate functionality of your application. Only these records will be available
for a Test Drive visitor.
5. Make sure that the Test Drive field is added to the View Application page on the Application Directory
or Marketplace portal. You can also edit properties of the Test Drive field.
6. Open the Application Directory portal or Marketplace and locate the published application. On the view
page, you will see a Test Drive button. If the Test Drive button is configured correctly, this button will be
enabled.
When a visitor to the Applications Directory portal or Marketplace clicks that button, they will be redirected
into designated tenant without logging in. The visitor will have access to all tabs and objects according to
permissions assigned to the Portal User role. The visitor will not be able to:
• Access administrative functions.
• Modify any data.
• Send emails, run import, etc.
Setting up ISV partners
If you wish to use Rollbase Private Cloud in an ISV model, you can create a new user record in the master
tenant and assign them the ISV Partner role. This will give the user limited access to your master tenant through
the ISV Partner application. See Using the ISV Partner application on page 945.
836 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Private Cloud security and access control
Private Cloud security and access control
Rollbase Private Cloud includes all of the security features of hosted Rollbase. However, with Private Cloud,
you can configure the following:
• Authentication method — You can use Rollbase's password authentication or you can use an external
authentication engine.
• Security levels and policies — Using Rollbase's password authentication, you can customize the security
level, password expiration policy, and password validation, and you can set up security questions for
authentication.
• API authentication on page 866 — When logging into Rollbase using an API, you can choose the authentication
mechanism to use for your selected authentication method.
• Protocol — You can configure Rollbase Private Cloud to use the HTTPS protocol.
For information about general security features, see Security and access control on page 643.
The following topics describe Private Cloud security options and how to configure them.
Supported Methods to Authenticate Users
Rollbase supports more than one authentication profile. This helps a Tenant admin to support more than one
Identity management system for a given application/solution and provide access to different users on that
application.
Key Features
• Use an internally configured Rollbase authentication for a tenant
• Use external authentication mechanism for a tenant
• Customize your own authentication mechanism for a tenant
• Enable different authentication profiles for different user roles in a tenant
• Configure a global authentication mechanism for all tenants
Support for multiple authentication will be applicable for per tenant authentication only. In case of global
authentication, the settings configured in the Control Panel properties will be considered for authentication.
Authentication Profile Options
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 837
Chapter 13: Installing and administering Private Cloud
• Default : A customer will have a default authentication profile for each UI and API. All the roles which are
mapped to default will be authenticated using the default authentication profile. For example - Consider that
a customer's default UI and API is set to Password authentication profiles and the admin role has default
selected for both UI and API. If the UI default authentication profile is updated to SAML, all users that belong
to the admin role will be authenticated through SAML from UI and password from API.
Note: When you create a new customer in a tenant, Password is set as the default authentication profile.
• None : Setting None will restrict users with that particular role from being authenticated into the system.
• This list includes Kerberos and Custom authentication profiles if these are configured by the master tenant.
This also includes API token and Password authentication profiles that are available by default as
authentication profiles across all tenants.
Note:
• When you migrate to Rollbase 5.1, the previously set authentication for a tenant will become the Default
authentication profile.
• A tenant can only have a single Password and OE authentication profiles.
The authentication mechanisms are categorized as:
• Password Authentication on page 840
• External authentication on page 847
Configuration of the different user authentication methods is discussed in detail in the following topics.
Creating an Authentication Profile
To perform this task, you must be logged in as an administrator in Rollbase Private Cloud.
Perform the following steps to create an authentication profile:
1. From the application menu in the banner, select Setup Home.
2. Under Administration Setup, click Authentication.
The Authentication Settings page appears displaying the exisitng Authentication Profiles (the password,
Kerberos and a list of default and system level authentication profiles) and the associated Roles table.
3. Click New Authentication Profile to create a new authentication profile.
The New Authentication Type dialog appears.
4. Choose one of the following authentication types:
• LDAP: For details, see Configuring LDAP Authentication on page 849. This only supports authentication
for a particular LDAP sub-tree. To authenticate users across multiple LDAP user groups, use LDAP
Advanced authentication.
• LDAP Advanced: For details, see Configuring LDAP Advanced Authentication on page 849. This supports
authentication across multiple user groups.
• HTTP Post: For details, see Configuring HTTP POST Authentication on page 851.
• HTTP Get: For details, see Configuring HTTP GET Authentication on page 852.
838 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Private Cloud security and access control
• OpenEdge: For details, see Configuring OpenEdge Authentication on page 852.
• SAML/ADFS: For details, see Configuring SAML/ADFS Authentication on page 857
5. Click Next.
Based on the selected authentication method, the relevant authentication page appears for you to configure
the authentication details. See the topic for your selected method for details.
6. Click Edit to edit a selected authentication profile.
Note:
Deleting an Authentication Profile
The Delete option for an Authentication profile is only enabled/visible if the authentication profile is not:
• Mapped to any role as either UI or API authentication
• Default UI/API authentication for that particular customer
• One of the four authentication types - Password, Kerberos, Custom and API token
From the Delete Authentication Profile? dialog, select the Yes, I want to complete this action checkbox
and click Conitnue to confirm deletion of the selected authentication profile.
Mapping Roles to Authentication Profiles
Mapping Roles to Authentication Profiles
To perform this task, you must be logged in as an administrator in Rollbase Private Cloud.
By default, all roles will be authenticated by the default authentication type. If any of the UI or API authentication
for a particular role is selected as NONE, the users under that role will not be able to login with that particular
authentication type.
Perform the following steps to map authentication profile to a role:
1. Select a role from the Roles table and click the associated Edit action. Alternatively, to edit multiple roles,
select the checkbox from the Roles grid header section and click Bulk Edit..
The Authentication profile role mapping dialog appears displaying the UI Authentication, API
Authentication and selected Role.
2. Select an authentication profile from the UI Authentication option.
This dropdown displays the list of following authentication profiles, if configured:
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 839
Chapter 13: Installing and administering Private Cloud
• Password
• LDAP/LDAP Adv
• HTTP GET/POST
• OE
• SAML/ADFS
• Custom
• Kerberos
• Default
• None
3. Select an authentication profile from the API Authentication option.
This dropdown displays the list of following authentication profiles, if configured:
• Password
• LDAP/LDAP Adv
• API Token
• HTTP GET/POST
• OE
• Custom
• Default
• None
Password Authentication
Use password authentication by creating a User record for each account. When you create a User record,
Rollbase generates a temporary password and sends it to the user's email account (by default, an email with
Welcome to Progress Rollbase as its subject). On the first log in, the Rollbase user is requested to change
the password against the temporary password. There is no field or template token corresponding to user's
password because Rollbase does not store actual users' passwords, but stores an encrypted (salted and
hashed) password instead.
The Welcome to Progress Rollbase email is based on a template included in the default Rollbase application
and you can modify it for your requirements. This template is named Welcome to Progress Rollbase and is
associated with the User object. See Email templates on page 199 for more information.
If a user is allowed to change the password for either the authentication profile (UI or API), the Change
Password page will be visible. This page allows password change for both UI and API authentication profiles.
If only one profile exists for which password could be changed, the tabs will not be present and only the options
for that profile will displayed on the UI.
840 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Private Cloud security and access control
When you use password authentication, Rollbase Private Cloud lets you configure the following user
authentication features:
• Security level - Controls login session behavior and password requirements.
• Password expiration policy - Specifies the number of days until a user password expires.
• Password expiration email notifications - Specifies when Rollbase sends password expiration email messages
to users.
• Custom validation formulas - Configures your specific security policy.
• Security questions for authentication - Requires users to answer security questions.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 841
Chapter 13: Installing and administering Private Cloud
Configuring Password Authentication
842 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Private Cloud security and access control
If you choose Password as your authentication method while Creating an Authentication Profile on page 838,
specify the following values to configure Password authentication for Rollbase Master Tenant:
Table 6:
Field Description
Security Level The built-in security level to implement. Specify Low,
Medium, or High. For more information about the
build-in security levels, see Built-in security levels on
page 844.
Expiration Policy The number of days before a password expires. When
a user's password expires, Progress Rollbase will
prompt the user to enter a new password during the
next login attempt. Leave this field blank to disable the
password expiration policy. You can configure a
Password expiration email notification on page 845 to
alert users that their passwords are going to expire.
Custom Validation Formula Custom validation code to be used in addition to the
validation rules specified by the built-in security level.
For more information about custom validation formulas,
see Custom validation formulas on page 846.
Password History Click to enable password history. This will help store
the previously used passwords and disallows recent
passwords during password management.
Select the number of previously used passwords to
be stored in the Passwords remembered.
Knowledge Factor Token
Enable this to add Knowledge Factor to the account
activation/password reset flow. The knowledge factor,
in a security context, is a category of authentication
credentials consisting of information that the user
possesses, such as a personal identification number
(PIN), a user name, a password or the answer to a
secret question. Any mandatory field of type Date, Text
and Integer from the User object definition can be
configured as the token field.
Security Questions Security questions users must answer to authenticate
to Rollbase. For more information about security
questions, see Security questions for authentication
on page 866.
NewUserPasswordActivationLinkExpiry Set the password expiratioin time in hours for new user
activation link to expire.
Minimum: 1
Default expiry time of the link: 2 hours
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 843
Chapter 13: Installing and administering Private Cloud
Field Description
Password Reset Expiry Time Set the password expiration time in hours for the reset
password link for existing users request to reset
password.
Default expiry time of the link: 2 hours
After specifying the above values, click Save to save your changes.
Built-in security levels
Rollbase supports three security levels per application: Low, Medium, and High. Rollbase Private Cloud
customers can both configure security and add more levels if desired see the XML in System Console >
System > Control Panel > Configuration > Security Levels. The standard Rollbase security levels and the
restrictions they enforce are described in the following table:
Security Level Low (default) Medium High
Password length 6+ 8+ 8+
(characters)
Password is No Yes Yes
case-sensitive
Password can include Yes No No
sequential or repeating
characters (like '123456'
or 'aaaaa')
Passwords must include No No Yes
non-alphabetical character
Block user account after N Never 10 5
unsuccessful login
attempts
Duration of block N/A 30 minutes 60 minutes
Minutes of inactivity before 240 (4 hours) 240 (4 hours) 240 (4 hours)
expiring user session
Minutes of usage before 480 (8 hours) 480 (8 hours) 480 (8 hours)
forcing user to re-login
Minutes to wait before 120 (2 hours) 60 (1 hour) 30 (1/2 hour)
expiring record lock
844 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Private Cloud security and access control
API Only Access
With API Only Access, a user's credentials can only be used to access REST and SOAP APIs. To create
such a user:
1. Create a regular user.
2. Edit the user and select API Only Access. If you do not see this check box on the user edit page, use the
page editor to add this field to the page. See Editing pages on page 369 for more information about the page
editor.
Setting and changing security levels
Security settings apply per customer tenant and control login session behavior and password requirements.
Built-in security levels on page 844 describes the available levels. Security levels apply only when using Rollbase
password authentication.
To set and change security settings for your tenant, follow these steps:
1. Navigate to the Setup home page:
• From an application page, do one of the following:
• Select Setup Home from the Rollbase menu.
• Select Setup Home from the application switcher
• From a setup page, select Setup Home from the application switcher.
2. In the Administration Setup section, click Authentication.
3. Verify that the Authentication Type is Password and click Next.
4. From the Security Level drop-down, select the security level.
Note: If you update the Security Level, certain users in your tenant may not be able to log in using their
existing credentials. Because of this, Progress recommends that you reset passwords for all your users
from the Users object tab using More actions...>Reset Password. Rollbase resets the passwords and
sends an email to all your users about their updated password. Alternatively, you can inform your users
about the change of security levels in your tenant and request them to change their passwords if necessary.
5. Click Save.
A message will confirm an update to the security level.
Password expiration email notification
If you set a password expiration policy for your organization when configuring Configuring Password
Authentication on page 842, you can enable email notification prior to password expiration.
To enable the email notification:
1. From the application switcher, navigate to the application settings for the Rollbase application.
2. Click Objects in the ribbon.
3. Click the User object.
4. Click Triggers in the ribbon.
5. Click Edit next to the Send Password Expiration Notification trigger.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 845
Chapter 13: Installing and administering Private Cloud
6. Click the This trigger is deployed check box.
7. In the Trigger Delay Time area, enter the number of days after the date of the last password update to
send the notification message:
8. Click Save.
The email template for that message is called Password Expiration Notification and you can customize it
the same way as you can any other email template. See Email templates on page 199 for more information.
You can create more than one notification trigger if desired.
Custom validation formulas
In addition to validation rules based on the security level, you can define a custom validation formula (rule) to
ensure that users' passwords satisfy your security policy. You must use password authentication to define a
custom validation formula.
To define a custom validation formula:
1. Navigate to the Setup home page:
• From an application page, do one of the following:
• Select Setup Home from the Rollbase menu.
• Select Setup Home from the application switcher
• From a setup page, select Setup Home from the application switcher
2. In the Administration Setup section, click Authentication.
3. On the Authentication page, enter the body of a JavaScript function with a single input parameter, password.
The function should return an error message for an invalid password or NULL for a valid password.
The following example ensures that the user's password includes at least one special character: '@'
or '#':
if (password.indexOf('@')<0 && password.indexOf('#')<0)
return "Password must include a special character.";
After specifying your custom validation formula, you can click Debug Formula to find and fix any errors
or inconsistencies in the formula.
846 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Private Cloud security and access control
External authentication
Rollbase supports the following external authentication methods, if you prefer external authentication:
• LDAP: Rollbase authenticates users based on a specific LDAP subtree.
• LDAP Advanced — Rollbase authenticates users based on LDAP, which can include multiple user groups.
• HTTP POST — Rollbase accesses an external system via HTTP POST to authenticate users.
• HTTP GET — Rollbase accesses an external system via HTTP GET to authenticate users.
• OpenEdge — Rollbase authenticates users based on user account information stored in an OpenEdge
Application Server.
• Windows (Kerberos) — Rollbase authenticates users using Kerberos authentication.
• Configuring SAML/ADFS Authentication on page 857 — Rollbase authenticates users using Security Assertion
Markup Language (SAML).
• Custom Authentication for Private Cloud on page 865 — Rollbase authenticates users using a custom
authenticator as an alternative to authentication methods provided by Rollbase.
Default Setting: The Default UI or Default API fields indicate the authentication profile that is currently set
as a default UI or default API authentication type. However, there is no compulsion that only one authentication
profile should be the default for both the UI & API authentications.
When configuring external authentication, parameters to connect to the external system are treated as templates
and accept the following tokens:
• {!loginName} — the log in name entered by the user
• {!password} — the password entered by the user
• {!ipAddress} — the IP address used by the user who is trying to log in
• Any field token from the User object, such as {!lastName}
See Example: external system single sign-on on page 848 for an example of configuring external authentication
using HTTP POST or HTTP GET.
Using external authentication
Instead of verifying passwords stored in Rollbase database, the system can perform an external call to verify
an existing Rollbase user's password. The following graphic illustrates the process:
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 847
Chapter 13: Installing and administering Private Cloud
If external authentication is set up, Rollbase is no longer managing users' passwords. In this case, the Change
My Password link is disabled. We strongly recommend that you modify the email template which welcomes
new users to clearly indicate the selected authentication method.
Example: external system single sign-on
Consider the following example of a single sign-on configuration:
• The external system has set of user accounts synchronized with the Rollbase tenant.
• The external system uses HTTP session IDs created during user login.
• The logged-in user of the external system should be able to access the Rollbase tenant without entering a
login name and password.
To accomplish this, first create a link on an external system page:
https://{!hostName}/router/servlet/Router?act=login&loginName={!userName}&password={!sessionId}
where:
• {!hostName} is the host name of Rollbase installation, for example, www.rollbase.com.
• {!userName} is the user name of the Rollbase user account (presumably shared with the external system).
• {!sessionId} is the session ID of the Rollbase instance.
Although the URL uses the parameter password, the actual password is securely stored in the external system
and is not exposed.
Next, configure the Rollbase tenant to use external authentication through an HTTP GET or HTTP POST
request. The request will include a user name and session ID supplied in the URL above. The external system
must verify that both values are valid and that they correspond to each other.
If these conditions are met, upon clicking the constructed URL, the user of the external system can access the
Rollbase instance without a need to enter a password, which remains securely stored in the external system.
848 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Private Cloud security and access control
Configuring LDAP Authentication
If you chose LDAP as the authentication method while Creating an Authentication Profile on page 838, specify
the following values to configure Rollbase to authenticate users using your LDAP system.
Default Setting: Selecting the Default UI or Default API fields indicate the authentication profile that is currently
set as a default UI or default API authentication type. However, there is no compulsion that only one
authentication profile should be the default for both the UI & API authentications.
Table 7:
Field Description
Name Type an authentication profile name.
Target URL The URL to access the LDAP system (typically,
ldap://<host-address>)
Security Authentication The authentication mechanism to implement.
For example, for a Sun LDAP service provider, this
can be one of the following strings: none, simple, or
sasl_mech, where sasl_mech is a space-separated
list of SASL (Simple Authentication and Security Layer)
mechanism names. The default value for this field is
simple.
Security Principal The name of the user or program doing the
authentication. Typically this is a query string to search
the LDAP database.
Security Credentials The credentials of the user or program doing the
authentication.
Additional fields Any additional details required to set up an LDAP call.
After specifying the above values, you must test your authentication method to check whether authentication
succeeds. To test your authentication method:
1. Under Test External Authentication, specify a valid login name and password.
2. Click Test External Authentication.
Note that you cannot save your changes until the test succeeds.
Configuring LDAP Advanced Authentication
The LDAP Advanced authentication type supports authentication across multiple LDAP user groups. In contrast,
the LDAP authentication type only works for users in a particular sub-tree. For example, an LDAP directory of
employees that is divided into groups based on their location would require LDAP Advanced authentication.
If you choose LDAP Advanced as your authentication method while Creating an Authentication Profile on
page 838, specify the following values to configure Rollbase to authenticate users using your LDAP system.
Default Setting: Selecting the Default UI or Default API fields indicate the authentication profile that is currently
set as a default UI or default API authentication type. However, there is no compulsion that only one
authentication profile should be the default for both the UI & API authentications.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 849
Chapter 13: Installing and administering Private Cloud
Field Description
Name Type an authentication profile name.
Target URL URL to access the LDAP system (typically,
ldap://<host-address>)
Base Distinguished Name The root distinguished name (DN) to use while running
queries against your directory server. Example:
• o=example,c=com
• cn=users, dc=ad, dc=example,dc=com
• For Microsoft Active Directory, specify the base DN
in the following format: dc=domain1,dc=local.
Replace domain1 and local for your specific
configuration. Microsoft Server provides a tool
called ldp.exe which is useful for finding out and
configuring the LDAP structure of your server.
Additional User DN The value to be used in addition to the base DN when
searching for and loading users. If no value is supplied,
the sub-tree search will start from the base DN.
For example, if an LDAP directory has users as well
as printers in it, and you only want to query the users
in the directory, you can pass the additional user DN
ou=Users in this field.
Authentication Type The authentication mechanism to implement.
For example, for a Sun LDAP service provider, this
can be one of the following strings: none, simple, or
sasl_mech, where sasl_mech is a space-separated
list of SASL (Simple Authentication and Security Layer)
mechanism names. The default value for this field is
simple.
Search Mode
The LDAP authentication requirements to search for
and get results from a search query. You can specify
the following based on your LDAP configuration:
• Anonymous: For LDAP directories that support
queries from a source that is not logged in.
• Authentication: Only authenticated users can
query the LDAP directory. If you choose this option,
two text fields open where you must specify:
• Admin Security Principal - The user name
• Admin Security Credential - The password
850 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Private Cloud security and access control
Field Description
Use Name Attribute The attribute field to use when loading the username.
Example:
• cn - Use the common name attribute.
• uid - Use the user ID attribute.
Additional Parameter Any other additional details required to set up an LDAP
call.
After specifying the above values, you must test your authentication method to check whether authentication
succeeds. To test your authentication method:
1. Under Test External Authentication, specify a valid login name and password.
2. Click Test External Authentication.
Note that you cannot save your changes until the test succeeds.
Configuring HTTP POST Authentication
If you choose HTTP POST as your authentication method while Creating an Authentication Profile on page
838, specify values for the following fields to set up a Post call to authenticate to an external system.
Default Setting: Selecting the Default UI or Default API fields indicate the authentication profile that is currently
set as a default UI or default API authentication type. However, there is no compulsion that only one
authentication profile should be the default for both the UI & API authentications.
Table 8:
Field Description
Name Type an authentication profile name.
Target URL URL that identifies the HTTP device and port (typically,
http://device:port-number/...)
HTTP Body The template for the body of the HTTP POST request
(typically a SOAP call). This must include tokens for
user's input.
HTTP Headers Valid HTTP request headers to pass as part of the
HTTP POST call. This is an optional field.
Note: The Content-Type header is available only for
backward compatibility. You can leave the header
value as blank to not include it as part of your HTTP
POST call.
Response Text Text that must be present in HTTP response to indicate
if the authentication was successful (for example,
<Authenticated>true</Authenticated> ).
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 851
Chapter 13: Installing and administering Private Cloud
After specifying the above values, you must test your authentication method to check whether authentication
succeeds. To test your authentication method:
1. Under Test External Authentication, specify a valid login name and password.
2. Click Test External Authentication.
Note that you cannot save your changes until the test succeeds.
Configuring HTTP GET Authentication
If you choose HTTP GET as your authentication method while Creating an Authentication Profile on page 838,
specify values for the following fields to set up a Get call to authenticate to an external system.
Default Setting: Selecting the Default UI or Default API fields indicate the authentication profile that is currently
set as a default UI or default API authentication type. However, there is no compulsion that only one
authentication profile should be the default for both the UI & API authentications.
Table 9:
Field Description
Name Type an authentication profile name.
Target URL URL that identifies the HTTP device and port (typically,
http://device:port-number/...))
HTTP Headers Valid HTTP request headers to pass as part of the
HTTP GET call. This is an optional field.
Response Text Text that must be present in the HTTP response to
indicate if the authentication was successful (for
example, <Authenticated>true</Authenticated> ).
After specifying the above values, you must test your authentication method to check whether authentication
succeeds. To test your authentication method:
1. Under Test External Authentication, specify a valid login name and password.
2. Click Test External Authentication.
Note that you cannot save your changes until the test succeeds.
Configuring OpenEdge Authentication
If you choose OpenEdge while Creating an Authentication Profile on page 838, specify values for the following
fields to implement OpenEdge Single Point of Authentication (SPA):
Note: You should understand how OpenEdge SPA works before configuring Rollbase to use this type of
authentication. For more information on OpenEdge SPA, see the Progress OpenEdge AppServer Administration
documentation.
Default Setting: Selecting the Default UI or Default API fields indicate the authentication profile that is currently
set as a default UI or default API authentication type. However, there is no compulsion that only one
authentication profile should be the default for both the UI & API authentications.
852 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Private Cloud security and access control
Field Description
Name Type an authentication profile name.
OpenEdge Realm URL The URL to connect users to the state-free AppServer. oerealm is the
name of the OpenEdge State-free AppServer where you deploy the
OpenEdge realm. (typically, appserver://host-name:port-number/oerealm).
OpenEdge Realm Class The realm service interface’s class path. SPA security implementation
for an OpenEdge REST Web application must specify the HybridRealm
interface class.
OpenEdge Domain The name of the domain to which the OpenEdge user must belong. Note
that only a single domain name can be specified and that only the users
in that domain will be authenticated.
OpenEdge Domain Access Code The code or a key required for a OpenEdge user to access the OpenEdge
domain. In that, in a REST service call, this code seals the client principal
token that validates and authenticates users.
Override hostname validation When enabled, OpenEdge authentication will not validate the hostname
of the OpenEdge Realm URL.
Typically, you use this option for testing purposes when your OpenEdge
Realm URL is secure (HTTPS) and you want to use a self-signed
certificate (as opposed to a CA Certificate Store file) for user
authentication.
Note that this option sets the noHostVerify property of JVM to true
and for security reasons, is not recommended for production systems..
Realm Token File The file name that holds a serialized ClientPrincipal used to authenticate
the realm service interface.
CA Certificate Store File The security certificate from the certificate store required for user
authentication.
Note: If your Realm URL is secure and it requires certificate, you must
provide your certificate in the CA Certificate Store File field for Rollbase
to access the URL. For example, AppserverDC://hostname/brokername
is not secure and doesn't require a certificate, and
AppserverS://hostname/brokername is secure and requires a certificate
for access.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 853
Chapter 13: Installing and administering Private Cloud
Field Description
Manages Password Enables the following password-management options:
• Password Guidelines: Text to display on the Change Password page.
• Use Security Questions to authenticate users: Allows you to
configure security questions users must answer upon login. See
Security questions for authentication on page 866 for information about
security questions. See Configuring security questions on page 866 for
information about configuring security questions.
When users change their password, the old password stored in the
Progress OpenEdge database must be updated with the new one. So,
before you enable the Manages Password option in Rollbase, you must
update your OERealm service interface method, SetAttribute(), in
OpenEdge with the change-password ABL logic. For information about
how to update SetAttribute() with the required ABL logic, see
Change-password ABL logic in Progress OpenEdge on page 854.
Super Admin Credential The Login Name and Password used to generate the client principal for
batch jobs and delay triggers. Provide these values if you plan to run
batch jobs and/or delay triggers on OpenEdge objects.
Guest User Credential The Login Name and Password used for portal access. Provide these
values if you plan to access OpenEdge objects from a Rollbase portal.
After specifying the above values, you must test your authentication method to check whether authentication
succeeds. To test your authentication method:
1. Under Test External Authentication, specify a valid login name and password.
2. Click Test External Authentication.
Note that you cannot save your changes until the test succeeds.
Change-password ABL logic in Progress OpenEdge
This section describes how to update the OERealm service interface method, SetAttribute(), with the
change-password ABL logic in Progress OpenEdge . You must understand OpenEdge Realm classes and
OpenEdge Single Point of Authentication (SPA) configurations to be able to implement the change-password
ABL logic. For more information about OERealm and SPA security configurations, refer to the OpenEdge
documentation.
854 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Private Cloud security and access control
You must consider the following for the change-password ABL logic in the SetAttribute() method:
• Rollbase employs the ATTR_PASSWORD attribute for changing passwords. Therefore, you must use the
same attribute, ATTR_PASSWORD, in SetAttribute() for changing passwords.
• As user account details are stored in Rollbase and user account passwords are stored in OpenEdge,
SetAttribute() must return True only if Rollbase enables users to change their password.
Therefore, if the Manages Password option is not enabled in Rollbase, SetAttribute() must return
False.
• If an error occurs while executing the change-password ABL logic, SetAttribute() must log the failure
and return False to Rollbase.
• The password field in the system table (_User in the sample) that stores the user accounts details can only
be changed by the user who owns the user account. Therefore, your change-password ABL logic must do
the following to be able to change a user's password:
• In the system table (_User in the sample) that stores the user account details, find the user record based
on user ID or number.
• Copy the user record into a temp-table.
• Delete the user record from the system table.
• Modify the password in the temp-table.
• Copy the temp-table values to the system table.
The following code-block shows a sample SetAttribute() method implementing the discussed considerations
for the change-password ABL logic:
Note: The following sample uses a new temp-table, ttUser. You must add the temp-table definition, DEFINE
TEMP-TABLE ttUser LIKE _User, to your OERealm service interface class.
METHOD PUBLIC LOGICAL SetAttribute( INPUT theUserId AS INTEGER, INPUT attrName AS
CHARACTER, INPUT attrValue AS CHARACTER ):
MESSAGE "Attempting to reset password for the attribute" attrName " for user number "
theUserId " with a value of " attrValue.
IF attrName EQ "ATTR_PASSWORD" THEN
DO:
FIND FIRST _User WHERE _User._User_number = theUserId NO-ERROR.
IF Available _user then
do:
Buffer-copy _user to ttUser.
ttUser._password = Encode(attrValue).
delete _User.
Buffer-copy ttUser Except _TenantId to _User.
RELEASE _User.
MESSAGE "Successfully changed password for user with id " theUserId.
RETURN true.
END.
ELSE
DO:
MESSAGE "User not found " theUserId.
RETURN false.
END.
END.
END METHOD.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 855
Chapter 13: Installing and administering Private Cloud
After updating the OERealm service interface class file, you must restart the server for the changes to take
effect.
Configuring Kerberos Authentication
Default Setting: Selecting the Default UI field indicates the authentication profile that is currently set as a
default UI authentication type. However, there is no compulsion that only one authentication profile should be
the default for the UI authentications.
Kerberos is an authentication profile which is configured by the master tenant using the System Console. This
authentication profile is common across all tenants. There can be only one Kerberos authentication profile.
If you choose Kerberos while Creating an Authentication Profile on page 838, the following are required:
• Rollbase must run on a named server (not localhost). Using the fully qualified domain name is recommended,
for example, http://rbinstance.mydomain.com. The hostname in the Rollbase license file will be
rbinstance.mydomain.com.
• Set up Active Directory (AD) as described below.
• Update the Shared Properties with the settings described below.
• Create new Customer(s) (tenants) as described below.
• Select Windows (Kerberos) as the authentication type as described below
• Set up browsers as described below.
Setting up Active Directory
Create a user in Active Directory as follows:
• The password does not expire.
• The password should not need to be reset on first login.
• Enable Trust this user for delegate to any service (Kerberos Only).
• setspn -a HTTP/<rbinstance>
• setspn -a HTTP/<rbinstance.mydomain.com>
Ensure that the two SPNs are not associated with any other Active Directory account.
Enabling Kerberos authentication in Shared Properties
The Rollbase server should be part of the Active Directory domain.
Set the following properties in Shared Properties:
• KerberosDomainName=<Windows Domain Name>, for example, MyDomain.MyCompany.com
• KerberosDomainController=<Domain Controller> (the Kerberos Ticket Issuing Server), for
example, MyTicketIssuingServer.MyDomain.MyCompany.com
• KerberosUsername=<AD account user name> (used for authentication)
• KerberosPassword=<AD account password> (used for authentication)
• Uncomment the property KerberosDebug.
• Authentication can be set as global or per tenant. To set as global, set the property
defaultAuthType=Kerberos.
Once you have set the properties, restart the Rollbase server.
856 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Private Cloud security and access control
Creating new Customer(s)
After restarting Rollbase, create Customers as follows:
1. Log into the master tenant as the master administrator.
2. Create a new Customer where the login name of user matches the username in Windows. The Customer
will be provisioned with the first admin having a local initial password.
3. Log into the new tenant as the first administrator using the password from the welcome email.
4. Add more users as needed. Each user’s login name should match their Windows username.
5. Enable support access so you can use the support login from the master tenant.
Selecting Windows (Kerberos) as the authentication type
Once you have enabled Kerberos authentication, select the authentication type:
1. From the Setup home screen, select Authentication under Administrative Setup.
2. In the Authentication Type table, select Windows (Kerberos).
3. Verify that you have completed the prerequisite steps and click Save.
4. Log out of Rollbase.
5. Open http://<rbinstance.mydomain.com>/router/login/loginKerberos.jsp in a browser from any machine
where the users that were added are logged into. This will log the users into their Rollbase accounts.
Setting up browsers
(Optional) Ensure that the browser identifies the host as an intranet site (Consult the respective browser help
for how to do this).
Enable Kerberos on Firefox:
http://docs.oracle.com/cd/E41633_01/pt853pbh1/eng/pt/tsec/task_EnablingKerberosAuthenticationinFirefox-836673.html
Troubleshooting tips
• Make sure DNS does not have invalid caches in any of the machines.
• SPNs should not be associated with multiple accounts. Sometime machine accounts are created with
hostname as SPNs automatically and this might clash with the delegate user account you create.
• If there is a cryptography error, install Java Cryptography Extension (JCE) for the appropriate JDK.
Configuring SAML/ADFS Authentication
Progress has verified support for SAML authentication using Onelogin, Salesforce, OpenAM (Progress ID),
and PingOne as the Identity Provider (IdP). ADFS is a Microsoft standard that is similar to SAML and conforms
to the SAML 2.0 specification. You can configure SAML/ADFS authentication details for individual tenants or
you can configure SAML/ADFS authentication details for all tenants.
If SAML/ADFS is being configured separately for each tenant, perform the following tasks:
1. Configuring the Rollbase instance to enable SAML/ADFS authentication.
2. Configure SAML authentication details for a tenant.
To configure the Rollbase instance so that all tenants use SAML/ADFS authentication, perform the following
tasks:
1. Configure the Rollbase instance to enable SAML/ADFS authentication.
2. Configure SAML/ADFS authentication details for all tenants
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 857
Chapter 13: Installing and administering Private Cloud
See the following topics for details about configuring SAML/ADFS authentication:
1. Configuring the Rollbase instance to enable SAML/ADFS authentication on page 858
2. Configuring SAML/ADFS Authentication for a Tenant on page 859
3. Configuring SAML/ADFS Authentication for all tenants on page 861
4. Example SP metadata file on page 863
Configuring the Rollbase instance to enable SAML/ADFS authentication
Before SAML or ADFS authentication is configured for a tenant or globally (all tenants), a master administrator
must perform the following tasks:
1. Generate a signed certificate (through Verizon, for example) or self-signed certificate. You can create a
self-signed certificate using the Java Keytool command or from a Web site that provides this service. For
example, the following command creates a self-signed certificate named Progress.jks (known as the
keystore in these instructions).
keytool -genkey -alias server -keyalg RSA -keysize 2048 -keystore Progress.jks
-dname "ON=Progress, OU=Development" -storepass myPassword
The keystore includes the public key certificate.
Note:
For long keys, such as those encrypted using AES-256, you will need to enable JCE unlimited strength in
your JRE. To do so, download the Unlimited Strength Jurisdiction Policy Files (in ZIP format) from one of
the following locations:
• Java 7: http://www.oracle.com/technetwork/java/javase/downloads/jce-7-download-432124.html
• Java 8: http://www.oracle.com/technetwork/java/javase/downloads/jce8-download-2133166.html
Extract the files and install them as instructed in the README.txt file.
2. Export the public key certificate from the keystore using Keytool as shown below:
keytool -export -keystore Progress.jks -alias server -file MyCertificate.cer
3. Create the SP metadata file. See https://docs.oracle.com/cd/E19461-01/819-7664/configspmeta/index.html
for information about creating this file. See Example SP metadata file on page 863 for an example of an SP
metadata file.
4. Log into Rollbase and navigate to System Console>Control Panel>Authentication.
5. Select the required authentication mode from the Authentication Mode drop-down list.
Note: If you select Global as the authentication mode, select the UI Authentication as SAML/ADFS and
the preferred API Authentication.
6. Specify the values for the following fields in SAML/ADFS SP Configuration section to configure SAML/ADFS
authentication.
858 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Private Cloud security and access control
Table 10:
Field Description
SPKey Store File The name of the keystore. In the prerquisite steps example,
Progress.jks.
SPKey Store Password The keystore password. In the prerquisite steps example, this is
myPassword.
SPKey Store Alias The keystore alias. In the prerquisite steps example, this is server.
Assertion Consumer Index The index of the URLs to be used in the SP metadata. In general,
multiple URLs are not supported by most of the IdPs, so you can set
this to the default of 0.
SP Metadata File The SP Metadata file.
7. For customers that will configure SAML or ADFS authentication at the tenant level, provide the public key
certificate to the customer administrators so they can configure SAML/ADFS authentication details for their
tenants. See step 2 for an example of generating this file using the Java Keytool command.
8. If you are using ADFS authentication: For SP-initiated login to work, you need to set the ADFS Secure
Hash Algorithm parameter to SHA-1. Rollbase uses the SHA-1 algorithm when signing SAML requests
and ADFS defaults to SHA-256.
Configuring SAML/ADFS Authentication for a Tenant
After the master administrator has configured Rollbase to enable SAML/ADFS authentication, the tenant
administrator must follow these steps to configure SAML or ADFS authentication details for the tenant:
1. Configure your IdP to add values for your Rollbase tenant. These values include the following; different
IdPs might have different labels for these. The labels shown below are for Salesforce:
• Entity ID — The value of the entityID attribute of the EntityDescriptor element in the SP metadata
file
• ACS (Assertion Consumer Service) URL — The value of the SAML ACS(Assertion Consumer Service)
URL property on the SAML/ADFS configuration page in Rollbase
• Encrypt SAML response — Upload the public key certificate file. The master administrator should provide
you with this file.
2. After configuring the IdP, obtain the IdP's SAML/ADFS metadata XML. You will need to save this as a file
and use it in the next step. This is usually provided by the IdP as either a file or as a URL containing the
metadata XML. If it is provided as a URL, save the XML in a file anywhere on your machine. This file is
referred to as the IdP metadata file in the next step. See Configuring the Rollbase instance to enable
SAML/ADFS authentication on page 858 for more information.
3. Select SAML/ADFS as the authentication method as described in Creating an Authentication Profile on
page 838.
4. Download the SP metadata file by clicking Download SP Metadata.
5. Specify the following values to configure a Rollbase tenant to authenticate users using SAML or ADFS:
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 859
Chapter 13: Installing and administering Private Cloud
Note:
Default Setting: Selecting the Default UI field indicates the authentication profile that is currently set as
a default UI authentication type. However, there is no compulsion that only one authentication profile should
be the default for the UI authentications.
Table 11:
Field Description
Name The name for the SAML configuration.
Issuer (IDP/ADFS Entity ID) This is the value of the entityID attribute of the EntityDescriptor
element in the IdP metadata file.This is a mandatory field.
Identity Provider/ADFS Metadata The IdP Metadata file.
Service Provider EntityID/Relying The entity ID of the service provider. This is a mandatory field. This is
Party Entity ID the value of the entityID attribute of the EntityDescriptor
element in the SP metadata file.
Attribute Map A pipe-separated mapping of the attributes in the form integration
name in Rollbase=attribute name sent from IdP. A user can choose
to map more than one attribute. The attribute loginName is the only
required and compulsory field to be mapped. You can also choose to
add more Attribute Mappings. For example:
firstName=givenName|lastName=sn|loginName=uid|city=city
Identity Provider Login URL The URL the users of the tenant should use to initiate SAML login.
This is the value of the Location attribute in the
SingleSignOnService element for the HTTP-POST binding in the
IdP metadata file.
Identity Provider Logout URL A custom URL can be configured by the SAML customer administrator
to redirect the user after logout.
Assertion Consumer Index The index of the URLs to be used in the SP metadata. In general,
multiple URLs are not supported by most of the IdPs, so you can set
this to the default of 0.
Authentication Context A comparison attribute on the AuthnContext request parameter to
Comparison Type indicate how an authentication context should be evaluated. The
authentication context will be evaluated based on the relative strengths
of the authentication context classes specified in the AuthnContext
request and the authentication methods offered by an IdP.
The four available comparison values are - better, exact, maximum,
and minimum. If no value is specified, it will default to minimum .
See setAuthentication on page 1256 and getAuthentication on page 1218
for more information.
Request Signature Method A signature method alogorithm to be used to sign the request being
sent to the IDP. You can select RSA-SHA1 or RSA-SHA256. The
default value is RSA-SHA1.
860 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Private Cloud security and access control
Note: Authentication Context Comparison Type parameter for SAML can be configured only at a tenant
level . For Global Level SAML configuration, the comparison value will always default to Minimum. If SAML
is the selected authentication type, then the parameter samlAuthnContextComparison will return the
set comparison value for getAuthentication REST API.
The following screen shows the properties for a sample configuration using Salesforce:
Configuring SAML/ADFS Authentication for all tenants
You can configure SAML/ADFS authentication globally to all tenants for the instance.
After you configure the instance to enable SAML/ADFS authentication, follow these steps to configure
SAML/ADFS authentication globally:
1. Configure your IdP to add values for your Rollbase tenant. These values include the following; different
IdPs might have different labels for these. The labels shown below are for Salesforce:
• Entity ID — The value of the entityID attribute of the EntityDescriptor element in the SP metadata
file
• ACS (Assertion Consumer Service) URL — The value of the SAML ACS(Assertion Consumer Service)
URL property on the SAML/ADFS configuration page in Rollbase
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 861
Chapter 13: Installing and administering Private Cloud
• Encrypt SAML response — Upload the public key certificate file. The master administrator should provide
you with this file.
2. After configuring the IdP, obtain the IdP's SAML/ADFS metadata XML. You will need to save this as a file
and use it in the next step. This is usually provided by the IdP as either a file or as a URL containing the
metadata XML. If it is provided as a URL, save the XML in a file. This file is referred to as the IdP metadata
file in the next step.
3. Log into Rollbase and navigate to System Console>Control Panel>Authentication
Note: Ensure Global is selected as the authentication mode.
.
4. In addition to the already configured SAML/ADFS SP details, specify the values for the following fields in
SAML/ADFS IDP Configuration section to configure SAML/ADFS for all tenants.
Table 12:
Field Description
Issuer (IDP/ADFS Entity ID) This is the value of the entityID attribute of the EntityDescriptor
element in the IdP metadata file.This is a mandatory field.
Identity Provider/ADFS Metadata The IdP Metadata file.
Service Provider EntityID/Relying The entity ID of the service provider. This is a mandatory field. This is
Party Entity ID the value of the entityID attribute of the EntityDescriptor
element in the SP metadata file.
Identity Provider Logout URL A custom URL can be configured by the SAML customer administrator
to redirect the user after logout.
Authentication Context A comparison attribute on the AuthnContext request parameter to
Comparison Type indicate how an authentication context should be evaluated. The
authentication context will be evaluated based on the relative strengths
of the authentication context classes specified in the AuthnContext
request and the authentication methods offered by an IdP.
The four available comparison values are - better, exact, maximum,
and minimum. If no value is specified, it will default to minimum .
See setAuthentication on page 1256 and getAuthentication on page 1218
for more information.
Attribute Map A pipe-separated mapping of the attributes in the form integration
name in Rollbase=attribute name sent from IdP. A user can choose
to map more than one attribute. The attribute loginName is the only
required and compulsory field to be mapped. You can also choose to
add more Attribute Mappings. For example:
firstName=givenName|lastName=sn|loginName=uid|city=city
Request Signature Method A signature method alogorithm to be used to sign the request being
sent to the IDP. You can select RSA-SHA1 or RSA-SHA256. The
default value is RSA-SHA1.
862 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Private Cloud security and access control
Note: Authentication Context Comparison Type parameter for SAML can be configured only at a tenant
level . For Global Level SAML configuration, the comparison value will always default to Minimum. If SAML
is the selected authentication type, then the parameter samlAuthnContextComparison will return the
set comparison value for getAuthentication REST API.
Example SP metadata file
The following is the content of an example SP metadata file.
<?xml version="1.0" encoding="UTF-8"?>
<md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata"
entityID="http://mymachine.mycompany.com:8830">
<md:SPSSODescriptor AuthnRequestsSigned="true" WantAssertionsSigned="true"
protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
<md:KeyDescriptor use="signing">
<ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
<ds:X509Data>
<ds:X509Certificate>MIIC0TCCAbkCAQAwXDELMAkGA1UEBhMCSU4xCzAJBCgKCAQEAmEwfAFLjgDO
BgNVBAoTCXJicHJpdmF0ZTELMAkGA1UECxMCUUExETAPBgNVBAMTCHJhamt1bWFyMIIBIjANBgkq
hkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAmEwfAFLjgDOEZk1AYPhX7dbYMXqkk4rF3uyYZeoMnnXP
Ls463GzGvVPnRgjTdIzm+1QOnkTx3BBu7kxlhtze2Sr7rtHLs1FYbzXREs5aVgIPnpkfuKdR9QND
aJJ1byxStnF+zI4feSYmHXsVWfHm24+FK0kCk3tSnw2/noXyW5xc2UbrGLYqaezpPSlf5WJ3isKF
lQr2k+HKXh4Rid4TUmEaoZXPAcB7QtkBYnIxzzmBoFCWSSsVldPRkaw=</ds:X509Certificate>
</ds:X509Data>
</ds:KeyInfo>
</md:KeyDescriptor>
<md:NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified</md:NameIDFormat>
<md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"
Location="http://mymacnine.mycompany.com:8830/router/login/loginSaml" index="0"
isDefault="true" />
</md:SPSSODescriptor>
</md:EntityDescriptor>
Adding a Relying Party Trust
Pre-requisites:
• Ensure that AD FS, AD DS and AD CS are installed and configured in the Windows server.
• Ensure that you have the keystore file-generated certificate configured in the Rollbase server for
authentication.
1. 1. In the Server Manager AD FS, select AD FS -> Tools -> AD FS Manager. The AD FS Manager screen
appears.
2. Select Trust Relationships -> Relying Party Trusts.
3. Right-click the Relying Party Trust directory and select Add Relying Party Trust. The Add Relying
Party Trust wizard appears.
4. Click Start. The Select Data Source screen appears.
5. Select Enter data about the relying party manually and click Next. The Specify Display Name screen
appears.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 863
Chapter 13: Installing and administering Private Cloud
6. Type the Display name and click Next. The Choose Profile screen appears.
7. Select AD FS profile and click Next. The Configure Certificate screen appears.
8. Ignore the Configure Certificate screen and click Next. The Configure URL screen appears.
9. Select the Enable support for the SAML 2.0 Web SSO protocol.
10. Configure the URL according to thedDomain on which Rollbase is hosted in the Relying party SAML 2.0
SSO service URL. For example: https://<domain>/router/login/loginSaml
11. Click Next. The Configure Identifiers screen appears.
12. Enter the Relying party trust identifier and click Add. For example : https://<domain> , the domain name
where Rollbase is installed. The identifier is added to the Relying party trust identifiers list. Click Next.
The Configure Multi-factor Authentication Now? screen appears.
13. Select I do not want to configure multi-factor authentication setting for this relying party trust at this
time and click Next. The Choose Issuance Authorization Rules screen appears.
14. Select Permit all users to access this relying party and click Next. The Ready to Add Trust screen
appears.
15. Verify that the configured details are correctly displayed in the Ready to Add Trust screen tabs. Click Next.
The Finish screen appears.
Next Task: Edit Claims Rule.
Editing Claims Rule
Pre-requisites: Add a Relying Party Trust.
1. Select Open the Edit Claim Rules dialog for this relying party trust when the wizard closes. Close the
wizard. The Edit Claim Rules dialog appears.
2. In the Issuance Transform Rules tab, click Add Rule. The Select Rule Template screen appears displaying
Choose Rule Type information.
3. Select Send LDAP Attributes as Claims as the Claim rule template. Click Next. The Configure Rule
screen appears.
4. Type the Claim rule name, select Active Directory as the Attribute store. In the Mapping of the LDAP
attributes to outgoing claim types field, select the following:
LDAP Attribute (Select or type to add more) Outgoing Claim Type (Select or type to add more)
User-Principal-Name UPN
Surname Surname
5. Click Finish. The Edit Claims screen appears, click Ok.
6. Open the Relying Party Trusts directory. Right click the newly added relying trust party and select
Properties. The ADFS configuration dialog appears.
7. In the Signature tab, click Add.
8. Add the certificate generated from the Keystore file which is configured in Rollbase server for authentication.
9. Click the Advanced tab and change the Secure hash algorithm to SHA-1 and click OK.
Rollbase is configured on AD FS for SAML/AD FS authentication. Here's how the AD FS configuration in
Rollbase looks like:
864 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Private Cloud security and access control
Name <Any name>
Issuer (IDP/AD <Entity ID> found in metadata.xml.
FS Entitiy ID)
Identity Typically, the metadata is found in the following URL:
Provider/AD FS
https://<Domain Name of the AD FS Server>/
Metadata
FedetationMetadata/2007-06/FederationMedata.xml
Service https://<Domain Name of Rollbase>
Provider/Relying
Party Entity ID
Attribute Map The loginName must be mapped to any AD server attribute like -
loginName=http://schemas.xmlsoap.org/ws/2005/05/identify/claims/upn
In addition, to the loginName, at least one other attribute must be mapped to the AD server
attribute like -
lastName=http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname
Identity This can by <any URL> where you have the logout logic flush out the user session.
Provider
Logout URL
Custom Authentication for Private Cloud
Private Cloud customers can develop and deploy a custom authenticator as an alternative to authentication
methods provided by Rollbase. Custom authentication is an authentication profile configured by the master
tenant using the control panel. This authentication profile is common across all tenants and there can be only
one Custom authentication profile.
Java Class for the Custom Authenticator
To create a custom authenticator:
1. Create a Java class that implements the com.rb.util.interfaces.IAuthenticator interface. At
minimum three methods must be implemented:
• A no-arguments constructor
• A method that will authenticate users by login name, password (which is passed from the login page)
and IP address, which returns true for success and false otherwise:
public boolean authenticate(ICustomer cust, String loginName, String password,
String ipAddress) throws Exception
• String representation (to be used by UI):
public String toString()
2. Compile this custom authenticator class into a JAR file.
3. Copy the JAR file to the TOMCAT_HOME/lib directory.
For a simple example, see CustomAuth.java included with the development kit
customt.zip\customt\src\auth\CustomAuth.java.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 865
Chapter 13: Installing and administering Private Cloud
To make Rollbase aware of the authentication option: Set CustomAuthClass in System Console → System
→ Control Panel → Cnfiguration -> Authentication → Custom section
Using a Custom Authenticator
Once you have completed the steps to create the Java and configuration classes, your custom authenticator
is a choice in the Administration Setup > Authentication page.
Select your custom authenticator, and then save the changes.
Your custom authenticator will be used to verify user credentials during login.
API authentication
When logging into Rollbase using REST and SOAP login APIs, three mechanisms for authentication are
supported:
• The authentication mechanism itself — Password for Password authentication, LDAP for LDAP
authentication, etc. Some authentication methods, such as Kerberos and SAML, do not support this
mechanism.
• API token authentication mechanism— A user can generate an API token to use instead of a password for
authentication. OpenEdge and Custom authentication methods do not support this mechanism. See Change
API Credential on page 718 for information about generating API tokens.
• Custom authentication — Authenticates the login API call via custom authentication logic.
You can set the API authentication mechanism for all tenants using the control panel property API
Authentication. See Control Panel on page 814 for details.
Security questions for authentication
Often security provided by password-based login is insufficient for customers, especially in the financial sector.
In this case, an administrator can set up security questions. After providing the correct login name and password,
a user must answer selected question(s) before proceeding to application pages.
Security questions are asked:
• After a user logs into Rollbase without a secure cookie.
• When a user's password is reset.
• When a user has changed answers to security questions.
• When a password expires (if an expiration policy was set).
• If a secure cookie was deleted or has expired.
Security questions for authentication are only available when the authentication method is Password or
OpenEdge.
For information about setting up security questions, see Configuring security questions on page 866.
For information about selecting and answering security questions, see Selecting and modifying your security
questions on page 24.
Configuring security questions
To configure security questions:
866 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Private Cloud security and access control
1. Navigate to the Setup home page:
• From an application page, do one of the following:
• Select Setup Home from the Rollbase menu.
• Select Setup Home from the application switcher
• From a setup page, select Setup Home from the application switcher
2. On the setup home page, click Authentication under Administration Setup.
3. Verify that the Authentication Type is Password or OpenEdge. Rollbase only supports security questions
for these authentication types.
4. Click Next.
5. If you are using OpenEdge authentication, select the Manages Password check box. Select the Use
Security Questions to authenticate users check box.
6. Select the number of questions a user must answer in their profile.
7. Select the number of previously answered questions a user must answer to be authenticated.
8. Enter up to 12 security questions. Each user can select from among these questions in their profile, and
must select the number of questions specified in Step 5. Do not change the wording of existing questions,
as it can confuse users who have already have answered these questions.
9. Click Save.
The following screen shows a configuration that includes four security questions. Each user must
answer two of these questions to save in their profile. When logging in, Rollbase randomly selects one
of the questions for the user to answer.
Users can select and provide answers to security questions in one of two ways:
• On the Change Password page.
• When logging in for the first time after the security questions were created.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 867
Chapter 13: Installing and administering Private Cloud
See Selecting and modifying your security questions on page 24 for details.
Configuring Rollbase Private Cloud to use HTTPS
By default, access to Rollbase Private Cloud from outside of a firewall uses the HTTP protocol. You can
configure it to use HTTPS instead. The procedure differs depending on whether you are using the evaluation
version or a licensed version of the product.
If you are using the evaluation version of the product:
1. Go to System Console > System > Shared Properties > General > Platform.
2. Change the value of HostName to localhost:8831 (for PAS) or to localhost 8081 (for Tomcat).
• Note that these are the default port numbers for PAS and Tomcat. If you have changed the HTTPS port
number for your configuration, use that number instead.
3. Save to restart the server for the changes to take effect.
If you are using a licensed version of the product:
1. In System Console > System > Shared Properties > General > Security enable IsSecureServer .
2. Save to restart the server for the changes to take effect.
Multi-server environments
There are two reasons why you would configure Rollbase as a multi-server environment. One is to improve
performance and the other is to provide high availability.
Performance
The performance of Rollbase is dependent on variables such as the following:
• Devoting as much CPU and memory as possible for production servers and database servers will help
increase performance.
• Low complexity applications can support up to 50 times more concurrent users than those that use a lot of
formulas, templates, custom filtering, reports, and anything that is processor or database-intensive. You
might be able to architect a system by creating different related applications rather than one all-inclusive
application. This might allow you to limit the functionality that requires more processing to a smaller number
of users.
• The fewer object definitions and applications in a particular customer tenant, the faster Rollbase can load
it into memory when requested, and the smaller amount of memory it will require.
Rollbase includes a set of auxiliary runtime components which can be run on a single host for small loads or
be deployed across multiple hosts for scaling purposes. As Rollbase usage grows, you can add instances of
these runtime components to provide adequate performance for all users. When you run Rollbase production
servers on multiple hosts, the router component calculates the least loaded server and directs newly logged
in users to that server.
Note: Verify that system clocks and system time zones on all servers are synchronized, or the system will not
be able to work properly.
868 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Multi-server environments
High Availability
High availability means that the system can continue to respond to requests despite individual component
failures. Besides individual component failure, a component can stop responding to requests because its host
failed, because of network outages--or even severe latency--, or in the case of Rollbase, if the web server or
the database failed.
See Configuring high availability on page 876 for more information about high availability in Rollbase.
Planning your multi-server architecture
Progress offers the following recommendations for scaling in a multi-server environment:
• Run database servers and PAS or Tomcat servers on different physical machines (not on virtual machines
using the same physical server).
• Hosts for databases should have high performance CPUs and at least 8GB of RAM.
• Hosts for PAS or Tomcat should have a 64-bit OS and have at least 8GB of RAM each (the more the better;
also make sure to allocate as much as possible to your Tomcat heap).
• If you are using Tomcat, be sure to install 64-bit versions of Java and Tomcat on each server.
• To provide load balancing, use an NGINX server to perform the routing of requests to the Tomcat instances.
You can have as many of these NGINX servers as needed for load balancing.
• Progress recommends performing load tests with an initial version of your infrastructure. This can help you
identify areas of slow performance and give you time to adjust before you have thousands of concurrent
users using the system.
With powerful servers and a low complexity app, you should be able to handle anywhere from 250 to over 1000
concurrent users per server. However, this depends on the database and CPU demands of your Rollbase
applications.
• Distributing load with PAS on page 869
• Distributing Load with NGINX and Tomcat on page 874
Distributing load with PAS
The high level steps to use multiple servers with PAS include:
• Creating N number of production servers by creating new PAS instances as described in Working with
instances on page 869.
• Configuring customer tenants with the Multi-Server Load attribute so that requests from users will span
multiple servers dynamically. When this setting is enabled, PAS and Rollbase distribute user sessions
across all available production sever components.
Note: If you are using TCMAN to create and run multiple instances of the Master Server (those with the Master
Web application in the webapps directory), you must copy the configuration files from the first Master Server
to the others. All Master Servers must have identical configuration files.
Working with instances
After you install the core Progress Application Server (PAS), you can create an instance.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 869
Chapter 13: Installing and administering Private Cloud
Instances are a standard Apache Tomcat feature. They allow you to create individual deployment and/or
development servers that are based on the core PAS that you installed.
The following figure illustrates the creation of multiple instances using the TCMAN command-line utility (with
syntax simplified).
Figure 1: Generating PAS instances
Instances are independently running copies of the core PAS. Each instance runs on its own JVM, has its own
configuration with unique ports, and hosts its own web applications. However, each instance runs a Tomcat
server that uses a number of common files from the same $CATALINA_HOME directory.
There are a number of advantages when you deploy your web applications to an instance of the PAS, rather
than deploying to the PAS that you installed. This practice prevents accidental corruption of the core executables,
configuration settings, and libraries. It also prevents accidental deletion of web applications if the core PAS is
removed when you uninstall a Progress PAS product.
Some additional advantages of instances are:
• Updates to the core Apache Tomcat server libraries and executables do not affect your web applications.
You avoid the necessity of updating the applications and/or re-configuring them.
• You can establish different security policies for each of the instances.
• You can tailor the JVM for individual applications, since each instance runs in its own JVM with its own
configuration.
• Instances provide you with quick way to create a test server for experimenting with new configurations and
applications without the danger of permanently corrupting an existing server.
• You can package an instance as a Web application and deploy it to other PAS core servers.
You use $CATALINA_HOME/bin/tcman.sh create command to create a new instance.
When you create an instance, the root directory of the instance is assigned to the CATALINA_BASE environment
variable within the scripts in its /bin directory. The root directory of the installed (core) PAS is assigned to the
CATALINA_HOME environment variable in the scripts in the instance's /bin directory. (Notice that the scope
of these environment variables is limited to the context of an individual instance's /binscripts.)
870 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Multi-server environments
All instances of a core PAS execute a set of common JAR files, scripts, and libraries from the following directories
on the parent server:
• $CATALINA_HOME/lib
• $CATALINA_HOME/common/lib
• $CATALINA_HOME/bin
However, each instance is created with :
• A $CATALINA_BASE/bin/ directory with its own copy of some of the scripts from the core PAS. These
include scripts for start up, shut down, deployment, running TCMAN actions, and so on.
• A $CATALINA_BASE/conf/ directory with its own copy of properties and configuration files.
• A $CATALINA_BASE/webapps/ which initially only contains the ROOT Web application.
• A number of directories that are initially empty. These include /logs, /temp, /work, and /common/lib.
Creating instances with TCMAN
TCMAN is a Progress extension of the basic Tomcat administrative utilities that simplifies instance creation
and management. A PAS instance runs the Tomcat executable of a core PAS, but it runs in a separate JVM,
is configured with its own unique ports, and other properties. Using PAS instances allows you to run a variety
of server configurations and to update the core server without re-deploying or re-configuring your Web
applications.
Note: If you are using TCMAN to create and run multiple instances of the Master Server (those with the Master
Web application in the webapps directory), you must copy the configuration files from the first Master Server
to the others. All Master Servers must have identical configuration files.
To create an instance using the TCMAN utility:
1. Open a command shell and navigate to $CATALINA_HOME/bin.
$CATALINA_HOME is the directory where you installed the core Progress Application Server.
2. Run tcman.sh create basepath (or tcman.bat on Windows systems) .
The base_path parameter specifies the path name where you will create the instance. It is the only required
parameter for the create action. If you are creating multiple running instances, you should override the
default port assignments by specifying the following parameters:
Specify the TCP port that listens for HTTP messages.
–p port_num
The default is 8080.
Specify the TCP port that listens for HTTPS
–P port_num
messages. The default is 8443.
You can also activate these ports:
Specify the TCP port to use to stop an instance.
–s port_num
(Required on Windows systems, optional on UNIX )
Specify the TCP port that listens for AJP13
messages, an Apache protocol for handling requests
–j port_num
from a web server to an application server. (Optional
on both Windows and UNIX systems)
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 871
Chapter 13: Installing and administering Private Cloud
See Create an instance (create) on page 913 for information about other parameters.
3. (Optional) Deploy remote management applications from $CATALINA_HOME/extras to the instance.
Remote management applications are not pre-installed, and installing them is a security decision. For
example, you might want to eliminate access to the configuration and control of instances by not deploying
management applications to production servers, while deploying management applications to development
servers.
To deploy a management application:
a) Open a command shell and navigate to $CATALINA_BASE/bin.
b) Run tcman.sh deploy '$CATALINA_HOME/extras/admin_webapp.war'.
The admin_webapp.war can be one of the following:
A Tomcat administration application used to get
server information and provide other functionality. It
host-manager.war should not be necessary to deploy
host-manager.war if you are using the TCMAN
utilities.
A Tomcat administration application which you must
deploy in order to run some TCMAN actions. See
manager.war the TCMAN Reference material for information on
which TCMAN actions require deployment of
manager.war.
Progress products can have web applications that
Progress applications
enable the use of their own administrative tools.
For example the following command line creates an instance of /psc/pashome in /psc/acme1 and
specifies its ports:
$: /psc/pashome/bin/tcman.sh create -p 8501 -P 8601 -s 8701 /psc/acme1
Server instance acme1 created at /psc/acme1
Instance management with TCMAN
TCMAN includes actions for configuring, starting, stopping, monitoring, and deleting instances.
The following table is a brief description of the instance management actions that you can perform with TCMAN.
Entries link to the reference topics that provide more details, syntax, and examples.
Action Purpose
create Create an instance of the Progress Application Server.
delete Remove the directory tree and all of the files in an instance.
start Start an instance of a Progress Application Server.
stop Stop a running instance.
872 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Multi-server environments
Action Purpose
config View, add, update, or delete the property values specified in
../conf/appserver.properties.
test Displays information on the configuration and environment of an instance. It also displays
information about error conditions.
instances Display all the instances created from the Progress Application Server installed in
$CATALINA_HOME.
unregister Stop tracking an instance by removing the instance's entry from the
$CATALINA_HOME/conf/instances.[unix|windows] file.
register Register an instance for tracking purposes. (Note that instances are registered for tracking
by default when they are created. The register action is only necessary if you explicitly
unregistered an instance.)
clean Truncate, move, or delete the log files located in the /logs directory of either the core
server or an instance.
version Show the Apache Tomcat runtime version and OS information for an instance.
Installing and running an instance as a Windows service
To install a Progress Application Server (PAS) instance as a Windows service, you must have administrator
privileges. On systems with User Account Control (UAC), you must disable UAC as well.
A service (called a daemon process on UNIX systems) is an application without a user interface that runs in
the background and provides core operating system functionality. Web servers like PAS and Tomcat typically
run as Windows services or UNIX daemons.
Note: If you run a PAS instance with the TCMAN start action, the instance runs in the context of the command
shell process. It is not available as a system service that can handle external client requests. The instance
must be registered as a Window service before you can start it as a service.
This is a summary of how to register and run a PAS instance as a Windows service:
1. Open a command prompt window.
2. Navigate to the core PAS /bin directory ($CATALINA_HOME/bin).
3. Run the TCMAN service action specifying an instance name and the register parameter . For example:
tcman service oepas1 register
where oepas1 is the name of the default instance created when you installed PAS for OpenEdge.
4. Run the TCMAN service action specifying an instance name and the start parameter. For example:
tcman service oepas1 start
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 873
Chapter 13: Installing and administering Private Cloud
Note: You can also use the TCMAN service action to check the running status, stop, and unregister a
PAS for OpenEdge instance as a Windows service. You can also use the Windows Microsoft Management
Console (MMC) or the sc config command to start, stop, and check the status of a service.
Installing and running a PAS instance as a Linux daemon
A daemon process (called a service on Windows systems) is an application without a user interface that runs
in the background and responds to requests. Web servers like PAS and Tomcat typically run as Windows
services or Linux daemons.
Note: If you run a PAS instance with tcman.sh start, the instance runs in the context of the command
shell process. It is not available as a system service that can handle external client requests. The instance
must be installed as a daemon process before you can run it as a functioning Web server.
The file $CATALINA_HOME/bin/daemon.sh can be used as a template for starting Tomcat automatically at
boot time as a child of the init process. For more information, see:
https://tomcat.apache.org/tomcat-8.0-doc/setup.html#Unix_daemon
However, you will need to consult with a system administrator before you can configure and run PAS as a
daemon process due to differences among Linux systems and because you need administrative privileges for
access to the system.
Distributing Load with NGINX and Tomcat
For distributing load on a multi-server architecture using 4 servers:
• Server 1: NGINX configured for routing requests
• Server 2: Dedicated to the database
• Server 3: Tomcat running a Master Server, Router Server and other standard Rollbase components
• Server 4: Tomcat running Production Server 1 (PROD1)
• Server 5: Tomcat running Production Server 2 (PROD2)
The high level steps to use multiple servers include:
• Creating N number of production servers (by installing Tomcat and production server component on a virtual
or physical machine).
• Configuring one or more NGINX servers to recognize each production server.
• Configuring Customer tenants with the Multi-Server Load attribute so that requests from users will span
multiple servers dynamically. When this setting is enabled, Tomcat and Rollbase distribute user sessions
across all available production sever components.
To install Rollbase instances on multiple hosts, verify that the Tomcat instances are installed on every machine
that will run Rollbase components. When copying WAR files, copy only the components that you wish to run
on particular machine. Make sure Production Server instances get WAR names that match component names:
for example, you would need to rename prod1.war after copying it to a different host. In the example shown
above, the following WAR files should be copied:
• Server 3: master.war, rest.war, router.war, search.war, storage.war, webapi.war
• Server 4: prod1.war
• Server 5: prod2.war (renamed version of downloaded prod1.war)
874 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Multi-server environments
Install and ConfigureNGINX
Configuring multiple instances of Rollbase components
With the appropriate license, you can distribute Rollbase components across multiple hosts.
Your license specifies the number of hosts that can run Rollbase software and must include the domain name
provided by your web server as the host name.
To set up an example architecture, follow these steps:
1. Installing NGINX on page 890 and Configuring NGINX on page 891
Note:
PAS is supported if you are configuring multiple instances of Rollbase components in a multi-server context
but without high-availability.
2. Use the multi-server license provided by Progress for the Rollbase Master Server installation.
3. Install the components on their respective hosts.
4. Specify the component details for the Master Server in the node-config.json to include entries for all
system components.
Note: Ensure that the server URL of each specific node is mentioned in the node-config.json of that
machine.
5. Start the database(s).
6. Start the Web server that is hosting the Rollbase Master Server instance.
7. Start the Web server on the hosts for production components.
8. Navigate to the System Console application System tab to verify that all of your components can be
monitored from the Master Server in the Components and Servers tab. Make sure that production servers
have the correct parameters.
Note: If you are using TCMAN to create and run multiple instances of the Master Server (those with the Master
Web application in the webapps directory), you must copy the configuration files from the first Master Server
to the others. All Master Servers must have identical configuration files.
Assigning a customer to a dedicated production server
By default, customers in a multi-server environment are loaded dynamically to any available production server.
An administrator logged into the master tenant can change this behavior by assigning any number of customers
to a specific production server.
Import jobs running on the Production server
Import jobs executed on the Production server provide the following benefits when compared to running these
on the Storage server:
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 875
Chapter 13: Installing and administering Private Cloud
• Cache — In a Production server, most data is cached to minimize database access. The Storage server
does not have the benefit of this cache, which resulted in more database access and affected performance.
Import jobs running in the Production server can take advantage of cached data and minimize database
access
• OpenEdge Data Objects — When an import job imports data into OpenEdge Data Objects, it requires a
password to authenticate to OpenEdge. The OpenEdge password is cached in the Production server but
is not available to the Storage server, which would result in an import failure. Import jobs running in the
Production server have access to the OpenEdge password and can successfully import data into OpenEdge
Data Objects.
• Concurrent Import Jobs — Import jobs are limited to one thread per component they run on. If you have
configured multiple Storage servers to have parallel import jobs, there is no longer any benefit in configuring
multiple Storage servers. Configuring multiple Production servers to load balance requests, including import
jobs, is the recommended approach to improve throughput. You can still configure multiple Storage servers
to load balance file/image access across the cluster and to segregate customer file data.
To assign customers to a dedicated server:
1. From the application switcher, navigate to System Console > Components.The Components page
appears.
2. Click the Edit link associated with the production server. The Edit Component Details dialog appears.
3. Select the IsDedicated checkbox to dedicate the production server and Save the changes.
4. Edit the customer records for the customers you want to assign to the production server:
a) Select the Customers tab.
b) Select the appropriate customer and click Edit.
c) Scroll down to the Zone Properties section:
Note: In case, the Dedicated Server field is not visible, click Page Options > Design This Page and
drag-drop the Dedicated Servercomponent from the Available Components panel to the Edit Page
and Save the changes.
d) From the Dedicated Server drop-down list, select the production server to assign for this customer.
e) Click Save.
Configuring high availability
Rollbase monitors each machine on which the components are running. Each machine sends a heartbeat as
configured in the cluster-config.xml file. All the nodes handle requests in a round-robin fashion. However,
in case of a failover, the remaining nodes in the group continue to handle the requests ensuring that there is
no disruption to the requests and Rollbase sends an email to the administrator. Once the failover issue is fixed,
the node is up and running and handles requests as usual.
876 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Multi-server environments
The diagram below shows a sample architecture for high availability in Rollbase:
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 877
Chapter 13: Installing and administering Private Cloud
• Load Balancing Layer:
ELB helps an IT team adjust capacity according to incoming application and network traffic. Users enable
ELB within a single availability zone or across multiple availability zones to maintain consistent application
performance.
ELB ensures that all Rollbase user requests are routed to the Nginx nodes in the Routing Layer.
• Routing Layer:
The Routing Layer is responsible for routing all the requests to the Rollbase components in the Rollbase
Production Space. It also serves static content.
• Rollbase Production Space:
All the Rollbase components run in the Rollbase Production Space. For example, in the diagram above,
each node in the the Master Group forms a cluster group. Each node contains a Master component. In
addition, the Master Group may also comprise Router, REST and SOAP components. All system admin
tasks are performed by the Master component.
Similarly,each node in the ProdGroup also forms a cluster group. Each of these nodes contains a Prod
component. The ProdGroup is responsible for handling application development and all end-user interactions.
The Search & StorageGroup comprises the search and storage components to handle all search and storage
related activities.
Note:
Progress recommends that you install your Router, REST, and SOAP servers on a single computer as it
results in faster REST API and SOAP API execution.
• Data Layer:
This layer comprises the entire Rollbase system data and tenant data.
• Rollbase System Console:
The Rollbase System Console provides an overview of system components, system health, logs and
performs administrative activities. See System Tab Interface on page 782 for details.
• AWS Console: Typically, a DevOps member uses the AWS Console to monitor the cluster set-up.
.
In the diagram, each node is a host in its group.
• Master++Group — Runs the Master server, Router server, REST server, and SOAP server
• ProGroup — Runs the Production server. Note that if you have multiple Production servers, each must run
on a different machine.
• Search&StorageGroup — Runs the Storage server and the Search server
• NGINX-1, NGINX- 2, NGINX...n — A high availability NGINX cluster based routing layer.
•
Note: High availability configurations are only supported in the current release for Rollbase running on Tomcat.
See Using your own instance of Tomcat on page 767 for more information.
878 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Multi-server environments
To understand how high availability is configured in Rollbase, let's consider a multi-server environment as
follows.
• Server 1 – Master, Router, REST, SOAP
• Server 2 – Prod
• Server 3 – Search and Storage
See Setting up Rollbase manually to learn how to set the above environment. Before configuring high availability,
you must ensure that the multi-server environment runs successfully.
To configure high availability, perform the steps below:
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 879
Chapter 13: Installing and administering Private Cloud
1. Replicate the multi-server set up to ensure each node can be configured for high availability. That is, the
multi-server environment should now have the following setup.
• Server 1 and 4 – Master, Router, REST, SOAP
• Server 2 and 5 – Prod
• Server 3 and 6 – Search and Storage
See Configure multiple instances of Rollbase components for information about configuring components
on multiple nodes.
2. Update the cluster-config.xml to add IP addresses or host names of all the nodes/machines (which
are discoverable by other machines) separated by a semi-colon. This file should be part of every
node/machine in the cluster.
<members>node1;node2;node3;node4;node5;node6</members>
See http://docs.hazelcast.org/docs/latest-development/manual/html/System_Properties.html for more
information on hazelcast system properties.
Note: When you add new Storage and Search servers, you must including the server IP addresses in the
cluster-config.xml to configure them for high availability.
3. Update master-cluster-config.xml add IP addresses or host names of all the master machines.
<members>master1;master2</members>
4. Update prod-cluster-config.xml add IP addresses or host names of all the prod machines.
<members>prod1a;prod1b</members>
Note:
• You can extend your multi-server environment to have more prod servers and configure high availability
by replicating the servers and updating the prod-cluster-config.xml to include the new prod
nodes.
• For example, let's say you added a third prod server. The prod-cluster-config.xml, in all prod
machines in the group, must be updated to include the IP address or the host name of the third prod
server.
<members>prod1a;prod1b;prod1c</members>
• If you want to create a new prod group, prod 2, you must configure a new node with prod2.war and
update node-config.json and prod-config.xml files accordingly. Follow the above step to add
more prod servers to prod2 group.
5. Install NGINX. See Installing NGINX for more information.
6. Configure NGINX. See Configuring NGINX for more information.
7. Copy the private.key file from rollbase\config\security folder and paste it into the nginx\conf
folder.
8. Update node-config.json with the NGINX webproxies information. This enables NGINX for Rollbase.
"webProxies" : [ { "url": "http://NGINXServerIPAddress:9080" } ]
880 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Multi-server environments
Note: If you want to configure an existing multi-server environment for high availability, you can add an
NGINX server by logging into Rollbase, navigating to System Console > System > Components > NGIX
Server, and entering the NGINX webproxies details.
9. Start the Rollbase instance.
Note: To verify that high availability is configured, in the System Console > System > Components, the
Host Name column should display the nodes of the cluster group.
Once you have your environment up and running, you can use the getTopology REST API to get the details
of the active logging Storage server, active Search server, and prod servers (is dedicated or not) and so on.
See getTopology for more information.
Note: When you have more than one Search servers configured for high availability, all servers are capable
of performing GET functions. However, only a single Search server, in a Search group, will be active to perform
WRITE functions. Similarly, when you have more than one Storage servers configured for high availability, all
servers are capable of performing all storage functions. However, only a single Storage server, in a Storage
group, will be a active logger.
Rollbase recommends you to use S3 or Azure as storage options while configuring high availability. However,
you can choose to use File System as the storage option by configuring it as a Network File System.
Example
For the above sample architecture, the following are the changes made to configure high availability.
cluster-config.xml
<members>172.21.63.26;172.16.114.24;172.16.81.100;172.21.81.26;172.18.110.24;172.16.11.24</members>
master-cluster-config.xml
<members>172.21.63.26;172.21.81.26</members>
prod-cluster-config.xml
<members>172.16.114.24;172.18.110</members>
node-config.json
"webProxies" : [ { "url": "http://172.20.65.26:9080" } ]
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 881
Chapter 13: Installing and administering Private Cloud
Troubleshooting
As explained earlier in this topic, high availability configurations are made manually in all nodes and as a result
of this, there might be some replication issues. You must ensure the following checks are made when servers
do not run as expected.
• node-config.json, cluster-config.xml, master-cluster-config.xml, and
prod-cluster-config.xml are updated as per your architecture.
• node-config.json is identical in all nodes that are a part of prod, Search, or Storage groups.
• The hazlecast port is enabled to accept requests. Refer the <port
auto-increment="false">5701</port> tag in cluster-config.xml.
Migrating to a Rollbase Cluster Setup on AWS
Before you begin: Ensure for the following:
1. You must have access to IAM (administrator) user for your account.
2. The existing VPC meets the following criteria:
• Two AZs
• Two Public Subnets
• Two Private Subnets
• Two NAT Gateways
3. Take the RDS snapshot before starting with the migration steps.
Note: Until the step# 4 of the Migrating to a Rollbase Cluster to a Rollbase Cluster section of this guide,
you can have your existing environment up and running.
882 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Multi-server environments
Getting Started with the Migration Process
1. Download aws.zip from Rollbase site and copy it to a Controller server (from where all deployment scripts
would be initiated)
2. Unzip the folder to view the following structure.
--- <aws>
|-- build (Holds scripts and data-files related to building of AMI)
|-- Cluster-config (Contains tools to run UI tool to generate your input files)
|-- deploy (Top folder bundling all Ansible deploy scripts/playbooks)
|-- scripts
|-- playbooks
|-- inventory
|-- config_files (Configuration files used as part of deployment process)
|-- scripts (Scripts that are executed as part of Cluster launch )
|-- ansible_templates ( CFN templates used for deployment)
|-- output ( Created at runtime – used to store output files of each playbook )
|-- migration (Created by user while copying config folder from existing server )
3. To create a new AMI for your deployment see Deploying Rollbase on AWS.
4. Move to the deploy folder.
5. From your existing Rollbase master, copy the config file contents to the migration sub folder.
6. Ensure that AWS_SECRET_KEY and AWS_ACCESS_KEY variables are sourced in your current shell.
7. Set JAVA_HOME variable point to Java1.8 on your controller machine and also include $JAVA_HOME/bin
in your PATH variable.
8. Login to your account and get values for the current VPC properties listed below.
• VPC ID
• PublicSubnet1
• PublicSubnet2
• PrivateSubnet1
• PrivateSubnet2
• AZ1
• AZ2
9. Run the Config-UI tool to generate the app-config and topology.json, ensuring that at least the same
number of Storage/Search servers that are in the current environment are retained.
10. Edit the app.config file and add the below properties with the values.
• RDS_DB_END_POINT: rlb-rds-cust-int-dbo.cobn7nddxtef.us-east-1.rds.amazonaws.com
• VPC: vpc-29e2844e
• vpcAZ1: us-east-1c
• vpcAZ2: us-east-1d
• vpcPubSubnet1: subnet-e6172dcc
• vpcPubSubnet2: subnet-b8da30f1
• vpcPvtSubnet1: subnet-e7172dcd
• vpcPvtSubnet2: subnet-bbda30f2
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 883
Chapter 13: Installing and administering Private Cloud
Migrating to a Rollbase Cluster Setup
884 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Multi-server environments
1. Run the init.yml script. This playbook would setup necessary files like encryption key file.
ansible-playbook -i ../inventory/host init.yml
2. Run update-vpc.yml
ansible-playbook -i ../inventory/host update-vpc.yml
This would re-use existing Public/Private Subnets and VPC that were provided as part of the input and
create the following resources:
• IAM Roles
• SQS-SNS
• EFS Volumes
• Security Groups
• S3 Buckets for storing configuration files
• Upload all required configuration files to S3
3. Run create-asg.yml
ansible-playbook -i ../inventory/host create-asg.yml
This playbook would create AutoScaling groups for Nginx/OPS and for each of the Role that is defined in
your topology.json
All of the AutoScaling Groups would include:
• Launch Configurations with userdata
• LifeCycle hooks
• Notification hooks with SNS sending messages to SQS queue
4. Run create.hooks.yml
ansible-playbook -i ../inventory/host create-hooks.yml
This playbook creates LifeCycle hooks that would be attached to the corresponding AutoScaling group.
Note: Ensure that at this point, your current application servers are completely shutdown and there are no
existing connections to the RDS.
5. Run launch-migrate-node.yml
ansible-playbook -i ../inventory/host launch-migrate-node.yml
To complete the migration, copy the existing Storage/Search data to the new cluster. This playbook when
executed, will launch an OPS node having /efs_data (EFS volume) mounted.
Also, the instance would have all ports open for the Private IP range (within VPC), which means that you
would be able to connect to this instance over scp from your existing Search/Storage machine which is in
the same VPC. If the storage is not huge, then do a ‘simple’ scp from the old (existing) Storage/Search
machine and copy over the contents to the new machine (recommended to zip, copy and then unzip)
For example: scp -r -i /tmp/my-keypair Files
[email protected]:/efs_data/storage1
However if the data is huge, then consider migrating the data ahead of time than actual application migration
date.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 885
Chapter 13: Installing and administering Private Cloud
Note:
Storage data needs to be copied to /efs_data/<storage_component_name>/ and Search data to
be copied to /efs_data/<search_component_name>.
So, if in your topology, there are more than 1 Storage/Search components, copy the data folders for each
component to its respective folder under /efs_data .
6. Ensure that the RDS is using DBSG created by this process and also update_5.0.0.0.sql has been executed
against all RDS used by your environment.
7. Launch the new cluster with the command ansible-playbook -i ../inventory/host
launch-cluster.yml
This playbook updates the ASG parameters – Min/Max/Desired number of instances to match the values
set in your topology.json and waits until the application endpoint is reachable. At the end of this command
execution, your environment becomes accessible.
Deploying Rollbase on AWS
Ensure that you have the following AWS account information in place:
• AWS_ACCESS_KEY
• AWS_SECRET_KEY
• EIP allocation IDs – 2 free IDs. These are needed to setup as public IP for your NAT gateway
• Key pair name
• SSL certificates uploaded to your AWS account (if planning to setup environment on Https)
• Execute the following command to get the SSL_ARN value. You can execute the following command aws
iam list-server-certificates on any ec2 machine or any Linux machine which has AWS cli libraries
installed.
Ensure that in addition to Java v8 (Java 9 is not supported), the following software is installed on a Linux
machine.
886 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Multi-server environments
Software Steps to install on Amazon Linux
Packer 1.0.4 • Download from
https://www.packer.io/downloads.html and extract
it.
• Set packer directory in PATH.
• Execute packer --version .
Result: This returns 1.0.4
Ansible 2.3 Execute the following commands:
• sudo yum update
• sudo yum-config-manager --enable epel
• sudo yum install ansible
• ansible --version
Result: Ensure that this returns ansible 2.3.1.0
Pip This is pre-installed in Amazon Linux 2017
Note: In the CentOS machine, you can install Pip with
the command yum install python2-pip
Botocore This is pre-installed in Amazon Linux 2017
Note: In the CentOS machine, you can install Botocor
with the command sudo pip install botocore
Boto3 Execute sudo pip install boto3
Python MySQL Module • Execute sudo yum -y install gcc
• Execute sudo yum install mysql
mysql-devel mysql-libs
• Execute sudo yum install python27-devel
• Execute sudo pip install MySQL-python
• Execute sudo pip install mysql-python
MySQL Client Execute yum install mysql client
Perform the following steps to deploy Rollbase cluster on AWS.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 887
Chapter 13: Installing and administering Private Cloud
1. Login to the Rollbase website ( https://www.progress.com/products/rollbase/try/try-it/private-cloud) and
download aws.zip.
2. Extract aws.zip. The directory structure looks like below after extraction.
|--- aws
|--- build
|--- cluster-config
|--- codebits
|--- lib.zip
|--- rollbase.zip
|--- webapps.zip
|--- deploy
|--- nginx
|--- installers
|--- build_version.txt
3. Copy third-party jars (e.g. mysql-connector.jar) to the … /aws/build/custom/lib directory.
|---aws
|---build
|---custom
|---lib
|--- mysql-connector.jar
4. Copy the third-party license files (e.g. Aspose.Pdf.lic) to the …/aws/build/custom/config directory.
5. Download Tomcat and Java software to the …/aws/installers directory.
6. Copy local_policy.jar and US_export_policy.jar to the …/aws/installers directory. (This
is optional and is required only in case of a 256-bit security key).
|--- aws
|---installers
|--- apache-tomcat-8.0.26.tar.gz
|--- jdk-8u144-linux-x64.tar.gz
|--- local_policy.jar
|--- US_export_policy.jar
Generating the Configuration Files
To get configuration details in a var.json file for creating an AMI, perform the following steps.
888 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Multi-server environments
1. Browse to …/aws/cluster-config/Cluster-Config-Generation-Tool-win32-ia32.
2. Execute Cluster-Config-Generation-Tool.exe(on Windows).
3. Provide the required details in the AMI Creation tab as shown below.
Note: Ensure that the downloaded versions of Tomcat and Java match with the versions entered in the
AMI Creation tab. If you chose "us-east-1" as the AWS Region, specify "ami-a4c7edb2" as the Base AMI
Id.
4. Click Generate AMi Configuration. The var.json file is generated.
5. Copy the var.json to the …/aws/build/config directory.
6. Provide required details in the Topology Configuration as shown below.
7. Click Generate Configuration. The topology.json is generated.
8. Provide required details in the Configuration tab.
Note: The Rollbase AMI field value can be entered only after performing the steps mentioned in the section
Creating a Rollbase AMI. Ensure that you update this value after creating the Rollbase AMI.
9. Click Generate App Configuration. The app.config file is generated.
10. Copy the topology.json and app.config files to the …/aws/deploy/config_files directory.
Creating a Rollbase AMI
Perform the following steps to create a Rollbase AMI.
1. Set AWS_ACCESS_KEY and AWS_SECRET_KEY as environment variables.
export AWS_ACCESS_KEY=XXXXXXXXXXXXXXXXXXXX
export AWS_SECRET_KEY=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
2. Run the following command to create a Rollbase Base AMI.
cd /aws/build
packer build -var-file=config/var.json templates/image_build_aws
Note: If you encounter any issues, to troubleshoot, run the above command in the debug mode by executing
the following:
packer build -debug -var-file=config/var.json templates/image_build_aws
Setting up the Environment
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 889
Chapter 13: Installing and administering Private Cloud
Perform the following steps to set up the environment.
1. Make sure that Java is set in PATH and execute the following commands:
cd /aws/deploy/playbooks
ansible-playbook -i ../inventory/host init.yml
ansible-playbook -i ../inventory/host deploy-vpc.yml
ansible-playbook -i ../inventory/host create-rds.yml
ansible-playbook -i ../inventory/host create-asg.yml
ansible-playbook -i ../inventory/host create-hooks.yml
ansible-playbook -i ../inventory/host launch-cluster.yml
Note: After completing the above steps, you should be able to access the environment with the following
URL - http://<hostname>/router/login/loginPrivate.jsp
• Every playbook is expected to be completed with success status and execution of next playbook depends
on the previous one.
• Playbooks are idempotent - if there is an issue with execution of a specific playbook, you can safely
re-run the same playbook after fixing the problem
Execute the below command to shutdown the entire cluster environment.
ansible-playbook -i ../inventory/host admin-shutdown-cluster.yml
Installing NGINX
This topic describes the procedure to install NGINX across different operating systems.
Ensure that ORACLE JDK v8 is installed (Java 9 is not supported), and respective environment variables are
set on the target machine.
Nginx is an HTTP and reverse proxy server. Rollbase uses Nginx as a reverse proxy / load balancer.
Rollbase bundles the Nginx package v1.11.10 for 6 different platforms along with static files. You can download
the Nginx package and run it on your desired platform.
Note: Ensure that you download Rollbase supported Nginx version. Also, ensure that the Linux versions match
with the Rollbase supported platforms.
Here are the list of supported platforms:
• Amazon Linux v2016.3
• Cent OS v7
• Red Hat Enterprise Linux v7
• SUSE Linux v11
• Ubuntu v15,v16
Download the respective package for suited platform and run it on your machine. Nginx bundle includes all
necessary configuration tailored to make it work with Rollbase. For the simplicity, customized the nginx bundle
for all the supported platforms to include nginx-clojure third party module.
890 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Multi-server environments
The version of Nginx being used is v1.11.10.
1. Download the nginx.tar.gz file based on the target machine's OS as indicated in the table below.
OS Filepath
Amazon Linux (v2016.3) <build location>/nginx/amazon-linux
Cent OS (v7) <build location>/nginx/centos/7/
Red Hat Enterprise Linux (v7) <build location>/nginx/rhel/7/
SUSE Linux (v11) <build location>/nginx/suse/11/
Ubuntu (v15, v16) <build location>/nginx/ubuntu/16/
2. Untar the downloaded file to /opt/nginx directory.
3. Go to /opt/nginx directory.
4. Run sbin/nginx executable using root permissions such as sudo ./sbin/nginx
5. Run command ps -ef | grep nginx to see whether nginx service has been
started.[ec2-user@ip-10-81-169-134 conf]$ ps -ef | grep nginx root 29560 1 0 09:12
? 00:00:00 nginx: master process ./nginx root 29617 29560 0 09:15 ? 00:00:01
nginx: worker process
• The worker processes count depends on the number of cores in the machine.
• Troubleshooting: If the nginx service has not started, check for the root cause in error.log file in the
logs folder. If the issue is encountered due to wrong jvm path, set jvm_path to correct location, as
shown below:
For ubuntu, jvm_path maybe is
"/usr/lib/jvm/java-8-oracle/jre/lib/amd64/server/libjvm.so";
For centos, jvm_path maybe is "/usr/java/jdk1.6.0_45/jre/lib/amd64/server/libjvm.so";
Configure Nginx.
Configuring NGINX
This topic describes the procedure to configure nginx.
Install Nginx on the target machine.
Configuration of Nginx is controlled by a configuration file, nginx.conflocated in
<nginx_install_dir>/conf directory. The nginx.conf file also includes the rb-upstreams.conf ,
rb-locations.conf and proxy.conf files which get stitched together.The rb-upstreams.conf &
rb-locations.conf contents are dynamically updated based on your topology when it is configured from
Rollbase. So, there is no necessity to manually change these files .
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 891
Chapter 13: Installing and administering Private Cloud
File Name Description
rb-upstreams.conf file This file contains the configuration related to upstream
servers. This defines a named pool of servers that
Nginx can then proxy requests to. For example,
upstream webapi {
server localhost:80;
}
upstream storage {
server localhost:80;
}
upstream search {
server localhost:80;
}
upstream router {
server localhost:80;
}
upstream rest {
server localhost:80;
}
upstream prod1 {
server localhost:80;
}
upstream master {
server localhost:80;
}
rb-locations.conf This file contains the mapping between client requests
and upstreams. For example,
location /webapi {
proxy_pass http://webapi;
}
location /storage {
proxy_pass http://storage;
}
location /search {
proxy_pass http://search;
}
location /router {
proxy_pass http://router;
}
location /rest {
proxy_pass http://rest;
}
location ~
/prod1/(.+\.(png|gif|ico|jpg|jpe?g|svg|css|js|map|woff|woff2))$
{
alias static/$1;
}
location /prod1 {
proxy_pass http://prod1;
}
location ~
/master/(.+\.(png|gif|ico|jpg|jpe?g|svg|css|js|map|woff|woff2))$
{
alias static/$1;
}
location /master {
proxy_pass http://master;
}
location /*.jsp {
proxy_pass http://master;
}
892 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Multi-server environments
File Name Description
proxy.conf This file contains proxy related configurations like
setting proxy headers, etc. If https upstream is enabled,
add respective proxy_ssl related configuration into this
file. For example,
proxy_redirect off;
proxy_set_header Host $host;
proxy_set_header X-Real-IP
$remote_addr;
proxy_set_header X-Forwarded-For
$proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto
$scheme;
proxy_set_header X-Forwarded-Host
$host:$server_port;
proxy_connect_timeout 90;
proxy_send_timeout 90;
proxy_read_timeout 90;
proxy_buffer_size 4k;
proxy_buffers 4 32k;
proxy_busy_buffers_size 64k;
proxy_temp_file_write_size 64k;
Serving Static Files from the Nginx machine
Once you configure the Nginx proxy in Rollbase, static files such as js, css & images will be served from the
Nginx machine. Nginx is bundled with all css, js & images files of the current Rollbase version and is available
for user to download. So, beginning with Rollbase 5.0 onwards, whenever a new version of Rollbase is available,
it is recommended that you update the Nginx also to the latest version if you are using an Nginx machine. You
can download the Nginx machine to respective platform and run it. When configuring the Webproxy (Nginx)
from Rollbase, the rb-locations.conf file required configuration is updated dynamically to serve static
files from the Nginx machine instead (and not form the Tomcat). Nginx serves only the master and prod machine
static files.
Sample rb-location.conf file below to serve static files for prod/master machines request from Nginx.
location ~ /prod1/(.+\.(png|gif|ico|jpg|jpe?g|svg|css|js|map|woff|woff2))$ {
alias static/$1;
}
location ~ /master/(.+\.(png|gif|ico|jpg|jpe?g|svg|css|js|map|woff|woff2))$ {
alias static/$1;
}
All static files available under static folder of Nginx folder such as \nginx\static\
Nginx Java Handler
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 893
Chapter 13: Installing and administering Private Cloud
Nginx runs on two ports - one port is used for external access and the other port is a java handler on which
Rollbase makes API calls for internal communication. The internal APIs are authenticated against a private
key which exists in both Rollbase and the Nginx machine. The private key should be available at
rollbase/config/security directory.
Note: You must copy the private.key from rollbase/config/security and paste it into nginx/conf
folder.
server {
listen 9080;
server_name localhost;
location / {
root html;
index index.html index.htm;
}
location /config/topology {
content_handler_type 'java';
content_handler_name 'com.rb.nginx.handler.ConfigHandler';
# Set this flag to true for proxy SSL
content_handler_property is.secure.server 'false';
# Authentication handler
access_handler_type 'java';
access_handler_name 'com.rb.nginx.handler.AuthenticationHandler';
location /config/environment {
content_handler_type 'java';
content_handler_name 'com.rb.nginx.handler.ConfigHandler';
# Authentication handler
access_handler_type 'java';
access_handler_name 'com.rb.nginx.handler.AuthenticationHandler';
location /config/files {
content_handler_type 'java';
content_handler_name 'com.rb.nginx.handler.ConfigHandler';
# Authentication handler
access_handler_type 'java';
access_handler_name 'com.rb.nginx.handler.AuthenticationHandler';
location /config/systemcheck {
content_handler_type 'java';
content_handler_name 'com.rb.nginx.handler.ConfigHandler';
# Authentication handler
access_handler_type 'java';
access_handler_name 'com.rb.nginx.handler.AuthenticationHandler';
}
location /health/ping {
content_handler_type 'java';
content_handler_name 'com.rb.nginx.handler.HealthCheckHandler';
}
error_page 500 502 503 504 /50x.html;
location = /50x.html {
}
894 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Multi-server environments
error_page 404 /404.html;
location = /404.html {
}
}
Configuring Nginx from Rollbase
You can configure the Nginx server in the following ways in Rollbase:
• Configuring Nginx from the System Console > System > Servers > NGINX Server
• Configuring Nginx through the node-config.json file
• Using REST API
To configure the nginx.conf file, do the following:
1. user: Set to root so that java plug-in module can get admin permission to the nginx installed location.
2. worker_processes: Set to auto. Nginx will automatically create the worker processes based on the machine
configuration. In general, count of workers depends on the number of cores.
3. Java handler listens on different port (default is 9080).
4. jvm_path: Used by java handler to initialize the jvm.
5. jvm_classpath: Class path for the java handler.
shared_map: Shared memory between the workers, used by the java handler. This is applicable only for
Linux platforms.
6. content_handler_type: Set to java
7. content_handler_name: Entry point for the java handler.
8. HTTPS configuration: Nginx access can be made secure with ssl configuration. You can add SSL at server
context, as illustrated in the example below.
9. https upstreams: Set content_handler_property is.secure.server to 'true' for location
/config/topology .
Adding the SSL at server context.
#
# HTTPS HANDLER
#
server {
listen 9443 ssl;
server_name prgs.example.com;
root html;
ssl_certificate cert.pem;
ssl_certificate_key cert.key;
ssl_session_cache shared:SSL:1m;
ssl_session_timeout 5m;
ssl_ciphers HIGH:!aNULL:!MD5;
ssl_prefer_server_ciphers on;
location / {
root html;
index index.html index.htm;
}
location /config/topology {
content_handler_type 'java';
content_handler_name 'com.rb.nginx.handler.ConfigHandler';
# Set this flag to true for proxy SSL
content_handler_property is.secure.server 'true';
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 895
Chapter 13: Installing and administering Private Cloud
# Authentication handler
access_handler_type 'java';
access_handler_name 'com.rb.nginx.handler.AuthenticationHandler';
}
location /config/environment {
content_handler_type 'java';
content_handler_name 'com.rb.nginx.handler.ConfigHandler';
# Authentication handler
access_handler_type 'java';
access_handler_name 'com.rb.nginx.handler.AuthenticationHandler';
}
location /config/files {
content_handler_type 'java';
content_handler_name 'com.rb.nginx.handler.ConfigHandler';
# Authentication handler
access_handler_type 'java';
access_handler_name 'com.rb.nginx.handler.AuthenticationHandler';
}
}
Optionally, add any post requirements, using <postreq>.
CDN Support
This topic provides an overview of the CDN support in Rollbase.
Rollbase provides Content Delivery Network (CDN) support to improve the performance and scalability of
various deployments. Enabling CDN support offers the following benefits:
• Increased server-side scalability: CDN support takes the load of serving static files from Tomcat and/or
Nginx.
• Lesser cost for private cloud installations.
• Improved client-side performance such as faster page loading on browser side due to domain sharding and
increased likelihood of caching files.
Enabling CDN Support
You can enable CDN support in Rollbase from System Console > Shared Properties > Customize > CDN.
After enabling CDN Support, if the CDN URLs are not specified, Rollbase will load the respective library from
local Tomcat or Nginx. See Shared Properties for more information. Rollbase provides the following CDN
Support while ensuring for backward compatibility:
• Boostrap
• Kendo
• Font Awesome
• Lato Font
896 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
CDN Support
List of CDN Servers
As long as the CDN URL follows the expected pattern, you should be able to use it without any problems. The
typical pattern is a base URL followed by a version and the library name. However, in the Shared Property,
provide only the base URL because Rollbase takes care of the version compatibility to ensure that there is no
mismatch of versions. For example, in case of Maxcdn, you can specify the base URL as
https://maxcdn.bootstrapcdn.com/bootstrap/ .
For example, for Kendo, when using https://kendo.cdn.telerik.com/ that results in including
the following:
<link rel="stylesheet" type="text/css"
href="https://kendo.cdn.telerik.com/2017.1.223/styles/kendo.common.min.css"
charset="utf-8">
<link rel="stylesheet" type="text/css"
href="https://kendo.cdn.telerik.com/2017.1.223/styles/kendo.mobile.all.min.css"
charset="utf-8">
<script type='text/javascript'
src='https://kendo.cdn.telerik.com/2017.1.223/js/kendo.all.min.js'></script>
<script type='text/javascript'
src='https://kendo.cdn.telerik.com/2017.1.223/js/kendo.timezones.min.js'></script>
<script type='text/javascript'
src='https://kendo.cdn.telerik.com/2017.1.223/js/jszip.min.js'></script>
<script type='text/javascript'
src='https://kendo.cdn.telerik.com/2017.1.223/js/pako_deflate.min.js'></script>
So, you may instead choose to enter the following:
BootstrapCdn: https://maxcdn.bootstrapcdn.com/bootstrap/
KendoCdn : https://kendo.cdn.telerik.com/
FontAwesomeCdn: https://maxcdn.bootstrapcdn.com/font-awesome/
LatoFontCdn:
https://fonts.googleapis.com/css?family=Lato:300,400,700&subset=latin,latin-ext
Note: The shared property contains only the base URL (ending with /) because several files can be served
from this path for all CDNs except in the case of LatoFontCdn. You may choose to use any other CDN server(s)
apart from the ones listed in this document.
Here's a list of tested CDNs:
Lato Font
http://fonts.googleapis.com/css?family=Lato:300,400,700&subset=latin,latin-ext
Kendo
Kendo CDN - http://docs.telerik.com/kendo-ui/intro/installation/cdn-service
The minified versions of all JavaScript files are available at:
• https://kendo.cdn.telerik.com/VERSION/js/FILENAME.min.js
• https://kendo.cdn.telerik.com/VERSION/styles/FILENAME.min.css
Bootstrap
Maxcdn:
• https://maxcdn.bootstrapcdn.com/bootstrap/3.3.7/css/bootstrap.min.css
• https://maxcdn.bootstrapcdn.com/bootstrap/3.3.7/js/bootstrap.min.js
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 897
Chapter 13: Installing and administering Private Cloud
Cloudflare:
• https://cdnjs.cloudflare.com/ajax/libs/twitter-bootstrap/3.3.7/css/bootstrap.min.css
• https://cdnjs.cloudflare.com/ajax/libs/twitter-bootstrap/3.3.7/js/bootstrap.min.js
jsDelivr
• https://cdn.jsdelivr.net/bootstrap/3.3.7/js/bootstrap.min.js
• https://cdn.jsdelivr.net/bootstrap/3.3.7/css/bootstrap.min.css
FontAwesome
MaxCDN:https://maxcdn.bootstrapcdn.com/font-awesome/4.7.0/css/font-awesome.min.css
CloudFlare:https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.7.0/css/font-awesome.min.css
jsDelivr: https://cdn.jsdelivr.net/fontawesome/4.7.0/css/font-awesome.min.css
Configuration file reference
The topics in this section describe Rollbase configuration files. The source of these files should be in the
config folder of the Master Server instance. When Rollbase starts, it saves these files, including the license,
in the database so the configuration is applied across all instances. You can edit many settings through the
UI. Those changes will be saved in the database and in the configuration files. If you change a setting by
manually editing a configuration file, you need to restart the PAS or Tomcat instance that is hosting the Master
Server.
license.xml
Progress provides this file to paying customers. In case of a new installation, save the license file in the config
directory and restart your application server. Alternatively, update the license information in System Console
> Control Panel > General > License and Usage.
Note: Altering the contents of the license file will cause a system error.
node-config.json
This XML file requires a Database node for each database used by your Rollbase Private Cloud system. Each
database node should contain the following child elements:
Note: The evaluation edition does not support multiple databases.
XML Node/Attribute Description
name (attribute) Symbolic name for database, used internally
Default: RB
isDefault (attribute) Marks database used by default for new customers
Default: None
898 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Configuration file reference
XML Node/Attribute Description
isExternal (attribute) Marks database which contains external data tables
Default: None
MinConnections (attribute) Number of database connections initially created in this pool
Default: MinConnections from Shared Properties
MaxConnections (attribute) Max number of database connections in this pool
Default: MaxConnections from Shared Properties
MaxInUseConnTimeMins Max time (in minutes) allowed database connection to be in use, connection
(attribute) will be closed when time is up
Default: MaxInUseConnTimeMins from Shared Properties
MaxNotUsedConnTimeMins Max time (in minutes) allowed database connection in a pool to be idle,
(attribute) connection will be closed when time is up
Default: MaxNotUsedConnTimeMins from Shared Properties
MaxConnLifetimeMins Max connection lifetime before closure (in minutes)
(attribute)
Default: MaxConnLifetimeMins from Shared Properties
ConnTimeoutSec (attribute) Timeout (in seconds) used when new database connection is created
Default: None, uses database default
TxIsolation Consult your database manual regarding transaction isolation level, if not
sure about this setting - do not use it (database default)
useTxRecovery (attribute) Enables or disables the default connection pooling's transaction recovery
and retry feature
When using Oracle or SQLServer databases and DataDirect drivers, Progress
recommends that customers omit this attribute and use the driver's retry
feature instead.
Driver Class name for JDBC driver used for this database
Default: com.mysql.jdbc.Driver
Url JDBC URL to database's service
jdbc:mysql://localhost:3306/RB_DBO
ConnectionRetryCount Number of times the driver retries connection attempts to the database server
(attribute) until a successful connection is established.
Default: 0
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 899
Chapter 13: Installing and administering Private Cloud
XML Node/Attribute Description
ConnectionRetryDelay Number of seconds the driver waits between connection retry attempts when
(attribute) the ConnectionRetryCount attribute is set to a positive integer
Default: 3
DbUser Database user
Default: account root
Password Password for user account
Default: None (must be specified prior to installation)
PAS command line reference
This section describes PAS tcman utility commands. For more information about PAS, including its security
model, see http://documentation.progress.com/output/ua/PAS/.
The tcman command
Purpose
TCMAN is a command-line utility for managing and administering PAS. On UNIX systems, you run the tcman.sh
script followed by appropriate TCMAN actions and options. On Windows systems, you run the tcman.bat
batch file, which is identical syntactically and functionally with tcman.sh.
Note: For the sake of brevity, all the syntax statements and examples in this reference show the tcman.sh
script.
Syntax
{$CATALINA_HOME|$CATALINA_BASE}/bin/tcman.sh action [general_options]
[action_options ]
Parameters
$CATALINA_HOME|$CATALINA_BASE
Specify whether to run TCMAN from the root directory of the installed PAS ($CATALINA_HOME) or
from the root directory of an instance ( $CATALINA_BASE). The context of where you run TCMAN
(whether from the /bin directory of the parent, or the /bin directory of an instance) affects which
server the utility acts on.
900 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
PAS command line reference
Note: TCMAN automatically determines the value of CATALINA_BASE from the directory where
you start it. When you run it from the /bin directory of an instance, the value of CATALINA_BASE
is the root directory of the instance. If you run it from the /bin directory of the installed Progress
Application Server, the value of CATALINA_BASE is the root directory of the installed server (which
is the same value as CATALINA_HOME).
action
Specify which TCMAN action to invoke.
general_options
Specify one or more of the TCMAN common options that can apply to most actions. Note that one
or more of the general options may be required by a specific action. For example, the list action
requires –u in order to pass a user name and password.
The output of tcman.sh help action includes a list of general options that are applicable to a
particular action.
The following table is a list of the common options:
Table 13: TCMAN general options
Common options Function
-u user_name:password Pass a valid user name and a password for HTTP
Basic access authentication.
-v Display verbose output.
-M URL
Override the default manager that manages Web
applications by specifying the URL of an
alternative manager. URL is expressed in the
following format:
{http|https}://host:port/manager_application
-B Override default
CATALINA_BASE
environment settings.
-n Debug the TCMAN action but do not execute
changes.
-I instance_name Run TCMAN from the /bin directory of the
specified instance.
action_options
Specify an option that applies to the selected action. These options are explained in the topics
that describe each action.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 901
Chapter 13: Installing and administering Private Cloud
Example
Run the help action from the core server (/psc/pashome) to display a list of available TCMAN actions:
/psc/pashome/bin/tcman.sh help
usage: tcman action [options...]
manager actions:
list list deployed applications
info list server info
deploy deploy application
undeploy undeploy application
reload reload application
status show server status
leaks show server memory leaks
enable start web application running
disable stop running web application
resources list server global resources
sessions list a web application's sessions
server actions:
create create a new server instance
delete delete server instance
config dump CATALINA_BASE configuration
clean clean/archive log files
instances list tracked server instances
register manually register an instance
unregister manually unregister an instance
start start this server
stop stop this server
version show the server version information
test test the server's configuration
general actions:
env show tcman execution environment
help show this information
Manager actions
This section details the actions available for deploying, running, and monitoring web applications on a server
instance.
List deployed applications (list)
Purpose
Display all the web applications that are deployed on an instance.
Note: This command may be used whether the instance is online or offline. However, the output differs. When
used offline, TCMAN simply shows a list of deployed application directories in the instance's web applications
directory. When used online, it provides additional run-time details about the deployed web applications.
To use this action, the Tomcat manager (manager.war) must be deployed on the instance if the instance is
online. You can deploy manager.war from $CATALINA_HOME/extras.
902 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
PAS command line reference
Syntax
tcman.sh list [general_options] [-u user_id:password ]
Parameters
general_options
Specify one or more of the options that can be used with any TCMAN action. Run tcman.sh help
list to see which general options are appropriate.
-u user_id:password
Specify a valid user name and password for HTTP Basic access authentication. (The default is -u
tomcat:tomcat.)
Note: This option is required if the server is online. It is not required if the server is offline.
Example
Show the Web applications deployed to acme1 when the instance is online:
/psc/acme1/bin/tcman.sh list -u tomcat:tomcat
OK - Listed applications for virtual host localhost
/:running:0:ROOT
/manager:running:4:manager
/oemanager:running:0:oemanager
/oeadapters:running:0:oeabl
Show the Web applications deployed to acme1 when the instance is offline:
/psc/acme1/bin/tcman.sh list
OK - Listing directories for /psc/acme1/webapps
/manager:stopped:0:manager
/oeadapters:stopped:0:oeabl
/oemanager:stopped:0:oemanager
/:stopped:0:ROOT
Display OS and server information (info)
Purpose
Display server and OS information for a running instance.
To use this action, the Tomcat manager (manager.war) must be deployed on the instance and the instance
must be running. You can deploy manager.war from $CATALINA_HOME/extras.
Use the test action to show configuration information about a server that is not running.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 903
Chapter 13: Installing and administering Private Cloud
Syntax
tcman.sh info [general_options] -u user_name:password
Parameters
general_options
Specify one or more of the general TCMAN options. Run tcman.sh help info to see which
general options are appropriate.
-u user_name:password
Pass a valid user name and a password for HTTP Basic access authentication. (The default is -u
tomcat:tomcat.)
Example
Display the OS and server information for the running instance named acme1:
$: /psc/pashome/tcman.sh info -I acme1 -u tomcat:tomcat
OK - Server info
Tomcat Version: Apache Tomcat/7.0.42
OS Name: Linux
OS Version: 2.6.18-164.el5
OS Architecture: amd64
JVM Version: 1.7.0_02-b13
JVM Vendor: Oracle Corporation
Deploy a Web application (deploy)
Purpose
Deploy a Web application (.war file) to a PAS instance whether the server is running (online) or is not running
(offline). TCMAN copies the web application to the server’s web application directory. If the server is online,
you must stop and restart it in order to complete the deployment.
Syntax
tcman.sh deploy [general_options] [-u user_id:password ] [-a app _name ]
war_file_path
Parameters
general_options
Specify one or more of the general TCMAN options. Run tcman.sh help deploy to see which
general options are appropriate.
904 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
PAS command line reference
-u user_id:password
Specify a valid user name and password for HTTP Basic access authentication.
Note: This option is required if the server in online. It is not required if the server is offline.
-a app _name
Specify a name for the web application. If you do not use this option, the application name will be
the same as the .war file name.
war_file_path
Specify the location of the web application .war file that you want to deploy.
Example
Deploy and rename oeabl.war (a web application that implements OpenEdge adapters) to the acme1 instance
of the core pashome server:
/psc/acme1/bin/tcman.sh deploy -a oeadapters /psc/pashome/extras/oeabl.war
OK - deployed /psc/pashome/extras/oeabl.war to local directory /psc/acme1/webapps
Note: The $CATALINA_HOME/extras directory (/psc/pashome/extras in the example above) also
contains number of instance management applications, including host-manager.war, manager.war, and
oemanager.war.
Undeploy a Web application (undeploy)
Purpose
Remove a Web application from running (online) or stopped (offline) instances. If the instance’s autodeploy
option is off, you must stop and restart a running server to complete removal. Note that the autodeploy option
is set in the .../conf/appserver.properties file and is off by default.
Syntax
tcman.sh undeploy [general_options] [-u user_id:password ] app _name
Parameters
general_options
Specify one or more of the options that can be used with any TCMAN action. Run tcman.sh help
undeploy to see which general options are appropriate.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 905
Chapter 13: Installing and administering Private Cloud
-u user_id:password
Specify a valid user name and password for HTTP Basic access authentication. (The default is -u
tomcat:tomcat.) This option is required if you are accessing an online instance.
app_name
Specify the name of the web application to remove.
Example
Remove the oemanager application from the acme1 instance:
/psc/acme1/bin/tcman.sh undeploy -u tomcat:tomcat oemanager
OK - Undeployed application at context path /oemanager
Reload a Web application (reload)
Purpose
Restart a deployed, running Web application so that the application can pick up changes to its classes or
libraries.
To use this action, the Tomcat manager (manager.war) must be deployed on the instance and the instance
must be running. You can deploy manager.war from $CATALINA_HOME/extras.
Note: The reload action does not reload the web application's web.xml file. To begin using changes to
web.xml, you must stop and restart the web application.
Syntax
tcman.sh reload [general_options] -u user_id:password app_name
Parameters
general_options
Specify one or more of the options that can be used with any TCMAN action. Run tcman.sh help
reload to see which general options are appropriate.
-u user_id:password
Specify a valid user name and password for HTTP Basic access authentication. (The default is -u
tomcat:tomcat.)
Note: This option is required if the server in online. It is not required if the server is offline.
app_name
Specify the name of the web application to restart.
906 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
PAS command line reference
Example
Reload the oemanager web application running on the acme1 instance:
/psc/acme1/bin tcman.sh reload -u tomcat:tomcat oemanager
OK - Reloaded application at context path /oemanager
List process ids (plist)
Purpose
List the process ids for all the processes that are running under an instance.
Syntax
tcman.sh plist [general_options] [-f]
Parameters
general_options
Specify one or more of the options that can be used with any TCMAN action. Run tcman.sh help
plist to see which general options are appropriate.
-f
Display verbose output. The output is indented and uses the plus (+) character to indicate parent-child
relationships.
Examples
Display process id's for the running instance, acme1 using the -v and -f options:
/psc/acme1/bin/tcman.sh plist -v
info: showing process ids for server 5942
5942 5963 5975 5988 6001 6015
/psc/acme1/bin/tcman.sh plist -f
5942
+5963
+5975
+5988
+6001
+6015
Notes
The plist action is useful for administrative tasks such as:
• Checking to see if processes persist after an instance is stopped.
• Checking if an multi-session agent process has started and is available
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 907
Chapter 13: Installing and administering Private Cloud
• Checking if an instance is running. Output is 0 if it is not running.
• Using the output (which is easily parsable) in administrative scripts.
Display detailed server status (status)
Purpose
List information from the core server’s memory, including web application statistics. Information includes memory
pool usage, connector thread status, and connector status. Output is in XML format. (Note that redirecting the
output to an XML viewer makes it more readable.)
To use this action, the Tomcat manager (manager.war) must be deployed on the instance and the instance
must be running. You can deploy manager.war from $CATALINA_HOME/extras.
Syntax
tcman.sh status [general_options] -u user_name:password [-f]
Parameters
general_options
Specify one or more of the general TCMAN options. Run tcman.sh help status to see which
general options are appropriate.
-u user_name:password
Pass a valid user name and a password for HTTP Basic access authentication. (The default is -u
tomcat:tomcat.)
-f
Return full status information.
908 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
PAS command line reference
Example
Display core server's memory and web application statistics and use xmllint to format for readability:
$: tcman.sh status -u tomcat:tomcat | xmllint --format -
<?xml version="1.0" encoding="utf-8"?>
<?xml-stylesheet type="text/xsl" href="/manager/xform.xsl" ?>
<status>
<jvm>
<memory free="453196832" total="520028160" max="1051394048"/>
<memorypool name="PS Eden Space" type="Heap memory" usageInit="50331648"
usageCommitted="48758784" usageMax="55967744" usageUsed="1525560"/>
<memorypool name="PS Old Gen" type="Heap memory" usageInit="469762048"
usageCommitted="469762048" usageMax="1006632960" usageUsed="63861584"/>
<memorypool name="PS Survivor Space" type="Heap memory" usageInit="8388608"
usageCommitted="1507328" usageMax="1507328" usageUsed="1444184"/>
<memorypool name="Code Cache" type="Non-heap memory" usageInit="2555904"
usageCommitted="3407872" usageMax="50331648" usageUsed="3303104"/>
<memorypool name="PS Perm Gen" type="Non-heap memory" usageInit="67108864"
usageCommitted="67108864" usageMax="134217728" usageUsed="47406400"/>
</jvm>
<connector name=""http-bio-8601"">
<threadInfo maxThreads="150" currentThreadCount="0" currentThreadsBusy="0"/>
<requestInfo maxTime="0" processingTime="0" requestCount="0" errorCount="0"
bytesReceived="0" bytesSent="0"/>
<workers/>
</connector>
<connector name=""http-bio-8501"">
<threadInfo maxThreads="300" currentThreadCount="10" currentThreadsBusy="1"/>
<requestInfo maxTime="2008" processingTime="2116" requestCount="10" errorCount="0"
bytesReceived="0" bytesSent="5838"/>
<workers>
<worker stage="S" requestProcessingTime="2" requestBytesSent="0"
requestBytesReceived="0" remoteAddr="127.0.0.1" virtualHost="localhost" method="GET"
currentUri="/manager/status" currentQueryString="XML=true" protocol="HTTP/1.1"/>
</workers>
</connector>
</status>
Display memory leaks (leaks)
Purpose
List Web applications with potential memory leaks.
To use this action, the Tomcat manager (manager.war) must be deployed on the instance and the instance
must be running. You can deploy manager.war from $CATALINA_HOME/extras.
Syntax
tcman.sh leaks [general_options] -u user_name:password
Parameters
general_options
Specify one or more of the general TCMAN options. Run tcman.sh help leaks to see which
general options are appropriate.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 909
Chapter 13: Installing and administering Private Cloud
-u user_name:password
Pass a valid user name and a password for HTTP Basic access authentication. (The default is -u
tomcat:tomcat.)
Example
Display memory leaks for web applications deployed on the acme1 server instance:
/psc/acme1/bin/tcman.sh leaks -u tomcat:tomcat
OK - Found potential memory leaks in the following applications:
/warehouse
Start a Web application (enable)
Purpose
Start a web application that is deployed but not running.
To use this action, the Tomcat manager (manager.war ) must be deployed on the instance and the instance
must be running. You can deploy manager.war from $CATALINA_HOME/extras.
Syntax
tcman.sh enable [general_options] -u user_id:password app_name
Parameters
general_options
Specify one or more of the options that can be used with any TCMAN action. Run tcman.sh help
start to see which general options are appropriate.
-u user_id:password
Specify a valid user name and password for HTTP Basic access authentication. (The default is -u
tomcat:tomcat.)
app_name
Specify the name of the web application to start.
Note: To start the ROOT web application, you can specify / or ROOT.
Example
Start the oeabl application deployed on the acme1 instance:
tcman.sh enable -u tomcat:tomcat oeabl
OK - Started application at context path /oeabl
910 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
PAS command line reference
Stop a Web application (disable)
Purpose
Stop a running Web application.
To use this action, the Tomcat manager (manager.war ) must be deployed on the instance and the instance
must be running. You can deploy manager.war from $CATALINA_HOME/extras.
Syntax
tcman.sh disable [general_options] [-u user_id:password ] app_name
Parameters
general_options
Specify one or more of the general TCMAN options. Run tcman.sh help disable to see which
general options are appropriate.
-u user_id:password
Specify a valid user name and password for HTTP Basic access authentication. (The default is -u
tomcat:tomcat.)
app_name
Specify the name of the web application to disable.
Note: To disable the ROOT web application, you can specify / or ROOT.
Example title
Disable the oeabl application running on the acme1 instance:
/psc/acme1/bin/tcman.sh disable -u tomcat:tomcat oeabl
OK - Stopped application at context path /oeabl
Display global server resources (resources)
Purpose
List the global resources used by the core server.
To use this action, the Tomcat manager (manager.war) must be deployed on the instance and the instance
must be running. You can deploy manager.war from $CATALINA_HOME/extras.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 911
Chapter 13: Installing and administering Private Cloud
Syntax
tcman.sh resources [general_options] -u user_name:password
Parameters
general_options
Specify one or more of the general TCMAN options. Run tcman.sh help resources to see
which general options are appropriate.
-u user_name:password
Pass a valid user name and a password for HTTP Basic access authentication.
(The default is -u tomcat:tomcat.)
Example
Display global resources for the running instance, acme1:
$: /psc/acme1/bin/tcman.sh resources -u tomcat:tomcat
OK - Listed global resources of all types
ServiceRegistry/ServiceRegistryFactory:com.progress.appserv.services.naming.ServiceRegistry
UserDatabase:org.apache.catalina.users.MemoryUserDatabase
Display Web application HTTP sessions (sessions)
Purpose
Display how many sessions are active for the specified Web application, categorized by their duration.
To use this action, the Tomcat manager (manager.war ) must be deployed on the instance and the instance
must be running. You can deploy manager.war from $CATALINA_HOME/extras.
Syntax
tcman.sh sessions [general_options] -u user_id:password app_name
Parameters
general_options
Specify one or more of the options that can be used with any TCMAN action.
-u user_id:password
Specify a valid user name and password for HTTP Basic access authentication. (The default is -u
tomcat:tomcat.)
912 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
PAS command line reference
app_name
Specify the name of the web application to analyze for session information.
Example
Show the active sessions for the manager application deployed on the acme1 instance:
/psc/acme1/bin/tcman.sh sessions -u tomcat:tomcat manager
OK - Session information for application at context path /manager
Default maximum session inactive interval 30 minutes
<1 minutes: 1 sessions
8 - <9 minutes: 2 sessions
9 - <10 minutes: 1 sessions
Server actions
This section details the actions available for creating and monitoring server instances.
Create an instance (create)
Purpose
Create a new instance of the core PAS server by running this action from /bin directory of the core server (
$CATALINA_HOME/bin/tcman.sh create).
Syntax
tcman.sh create[general_options][-f][–p port_num] [-P port_num]
[-s port_num] [-j port_num] [-m uid:pwd] [-W pathname] [-N instance_name]
[-U user_id ] [–G group_id ] [-Z {prod | dev }] base_path
Parameters
general_options
Specify one or more of the general TCMAN options. Run tcman.sh help create to see which
general options are appropriate.
–f
Copy all deployed web application archives (.war files) from $CATALINA_HOME to the new instance.
–p port_num
Specify the TCP port that listens for HTTP messages. The default is 8080.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 913
Chapter 13: Installing and administering Private Cloud
–P port_num
Specify the TCP port that listens for HTTPS messages. The default is 8443.
–s port_num
Specify the TCP port to use to stop an instance. On Windows systems, you must specify a shutdown
port. On UNIX, shutdown ports are optional.
–j port_num
Specify the TCP port that listens for AJP13 messages (an Apache protocol for handling requests
from a web server to an application server). The default is 8009.
-m uid:pwd
Specify a user name and password that will be required to access Tomcat container-level security,
which includes the manager and oemanager web applications. Replaces the defaults
(tomcat:tomcat) in /conf/tomcat-users.xml.
–W pathname
Specify the directory where web applications will be deployed. The default is
$CATALINA_BASE/webapps.
–N instance_alias
Specify an alias for the instance. If you do not specify an alias, the instance name will be the name
of the directory where the instance is created.
Note:
All instances are automatically registered for tracking when they are created. However, for tracking
to function, the instance name must not contain spaces or any of the following characters: "[ .
# | ] $ ? + = { / , }"
–U user_id
Specify the user-id of the owner of all the files and directories of the instance. The default is the
user-id of the current process. –G must be specified if you use this option.
–G group_id
Specify the group-id of the owner of all the files and directories of the instance. The default is the
group-id of the current process. –U must be specified if you use this option.
-Z {dev | prod }
Specify the security model of the instance to development (dev) or secure (prod).
A typical use of this option is for testing web applications in a secure server environment before
packaging and deploying.
Note: The -Z prod option does not create a production server. To actually create a production
server, you must have a production server license.
914 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
PAS command line reference
base_path
Specify the pathname where you will create the instance.
Example
Create an instance of /psc/pashome in /psc/acme1:
$: /psc/pashome/bin/tcman.sh create -p 8501 -P 8601 -s 8701 /psc/acme1
Server instance acme1 created at /psc/acme1
Delete an instance (delete)
Purpose
Remove the directory tree and all of the files in an instance. Alias tracking is disabled for servers that are
removed.
To execute this action, the instance cannot be running.
Note: You cannot recover any files or directories removed by the delete action. Backup anything you want
to save before launching this action.
Also note that you cannot use delete to remove the installed, root server ( $CATALINA_HOME ).
Syntax
tcman.sh delete [general_options] [-y][base_path|alias_name]
Parameters
general_options
Specify one or more of the general TCMAN options. Run tcman.sh help delete to see which
general options are appropriate.
-y
Delete everything without prompting for confirmation.
base_path
Specify the pathname of the instance that you intend to delete.
alias_name
Refer to the instance that you intend to delete by its alias rather than its pathname.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 915
Chapter 13: Installing and administering Private Cloud
Example
Delete the instance of pashome that was created in /psc/acme3:
$: /psc/pashome/bin/tcman.sh delete /psc/acme3
The following directory tree will be removed permanently:
( WARNING all deployed web applications will be DELETED!! )
/PAS/wrkdir/acme3
/PAS/wrkdir/acme3/conf
/PAS/wrkdir/acme3/temp
/PAS/wrkdir/acme3/common
/PAS/wrkdir/acme3/common/lib
/PAS/wrkdir/acme3/logs
/PAS/wrkdir/acme3/webapps
/PAS/wrkdir/acme3/webapps/ROOT
/PAS/wrkdir/acme3/webapps/ROOT/static
/PAS/wrkdir/acme3/webapps/ROOT/static/error
/PAS/wrkdir/acme3/webapps/ROOT/static/auth
/PAS/wrkdir/acme3/webapps/ROOT/META-INF
/PAS/wrkdir/acme3/webapps/ROOT/WEB-INF
/PAS/wrkdir/acme3/webapps/ROOT/WEB-INF/adapters
/PAS/wrkdir/acme3/webapps/ROOT/WEB-INF/adapters/rest/PingService
/PAS/wrkdir/acme3/webapps/ROOT/WEB-INF/adapters/soap
/PAS/wrkdir/acme3/webapps/ROOT/WEB-INF/classes
/PAS/wrkdir/acme3/webapps/ROOT/WEB-INF/classes/com
/PAS/wrkdir/acme3/webapps/ROOT/WEB-INF/classes/com/progress
/PAS/wrkdir/acme3/webapps/ROOT/WEB-INF/classes/com/progress/appserv
/PAS/wrkdir/acme3/work
/PAS/wrkdir/acme3/bin
Type 'yes' to continue
yes
Delete operation complete
server removed at /PAS/wrkdir/acme3
Display and manage an instance's configuration (config)
Purpose
View, add, update, or delete the property values specified in ../conf/appserver.properties and in
../conf/catalina.properties.
When you run tcman.sh config with no parameters, it displays the core Tomcat server’s configuration, and
all the properties in both .../conf/appserver.properties and .../conf/jvm.properties. Note,
however, that you can only view jvm.properties. You cannot modify its contents with the config action.
Syntax
[general_options]
tcman.sh config
[prop_name|prop_name=value|+prop_name=value|~prop_name]
Parameters
general_options
Specify one or more of the general TCMAN options. Run tcman.sh help config to see which
general options are appropriate.
916 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
PAS command line reference
prop_name
Display the specified property and its value.
prop_name=value
Set the value of a property that exists in .../conf/appserver.properties.
+prop_name=value
Add a new property to .../conf/appserver.properties and set its value.
~prop_name
Remove the specified property from .../conf/appserver.properties.
Examples
Show the configuration and properties of acme1, an instance of the core server, pashome:
$: /psc/acme1/bin/tcman.sh config
Using CATALINA_BASE: /psc/acme1
Using CATALINA_HOME: /psc/pashome
Using CATALINA_TMPDIR: /psc/acme1/temp
Using JRE_HOME: /tools/linuxx86_64/java64/jdk1.7.0_02/
Using CLASSPATH: /psc/pashome/bin/bootstrap.jar:/psc/pashome/bin/tomcat-juli.jar
Using CATALINA_PID: /psc/acme1/temp/catalina.pid
Server version: Apache Tomcat/7.0.42
Server built: Jul 2 2013 08:57:41
Server number: 7.0.42.0
OS Name: Linux
OS Version: 2.6.18-164.el5
Architecture: amd64
JVM Version: 1.7.0_02-b13
...
Display the value of a single property:
$: /psc/acme1/bin/tcman.sh config psc.as.http.port
psc.as.http.port=8501
Update the value of a property that exists in the appserver.properties file and then check the value:
$: /psc/acme1/bin/tcman.sh config psc.as.http.port=6543
$: tcman.sh config psc.as.http.port
psc.as.http.port=6543
Add a new property/value pair to the appserver.properties file and check the value:
$: /psc/acme1/bin/tcman.sh config +my.home.dir=/home/jarhead
$: tcman.sh config my.home.dir
my.home.dir=/home/jarhead
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 917
Chapter 13: Installing and administering Private Cloud
Update the server certificate in the catalina.properties file (see
https://docs.oracle.com/cd/E19879-01/821-0185/ablqz/index.html for information about generating, exporting,
and downloading a new server certificate):
$: /psc/acme1/bin/tcman.sh config psc.as.https.keyalias=myNewCert
Remove a property/value pair from the appserver.properties file and check if deletion was successful:
$: /psc/acme1/bin/tcman.sh config ~my.home.dir
$: tcman.sh config my.home.dir
Property does not exist - my.home.dir
Caution: There are no restrictions to property removal. The server will be unable to start if you remove a
property required by conf/server.xml.
Notes
• All property names are case sensitive.
• You cannot enter multiple property names (prop_name) on the command line to view, update, or add
properties to the appserver.properties file.
• You cannot use the config action to update existing values or add new values to the jvm.properties file
Display or modify the server features of an instance (feature)
Purpose
View, enable, or disable the server features contained in the /conf/server.xml file of an instance.
When you run tcman.sh feature with no parameters, it displays a list of the features (and their current
status) that you can enable or disable. You can also display the status of a single server feature. After viewing
the status of a feature, you can use tcman.sh feature to change its setting.
Syntax
tcman.sh feature [general_options] [feature_name[={on|off}]]
Parameters
general_options
Specify one or more of the general TCMAN options. Run tcman.sh help feature to see which
general options are appropriate.
feature_name
Specify one of the features defined in an instance's conf/server.xml file. Running tcman.sh
feature without feature_name displays a list of all the features.
918 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
PAS command line reference
on
Enables the named feature.
off
Disables the named feature.
Example
Display the list of server feature settings for acme1, enable AJP13 (Apache JServ Protocol. version 1.3), and
verify that the feature is enabled:
$: /psc/acme1/bin/tcman.sh feature
SecurityListener=off
JMXLifecycle=off
PSCRegistry=on
HTTP=onHTTPS=on
AJP13=off
Cluster=off
UserDatabase=on
JAASRealm=off
LDAPRealm=off
PASInstrument=off
RemoteHostValve=on
RemoteAddrValve=onSingleSignOn=on
AccessLog=on
CrawlerSessionManager=on
StuckSessionValve=on
$: /psc/acme1/bin/tcman.sh feature AJP13=on
$: /psc/acme1/bin/tcman.sh feature AJP13
AJP13=on
Notes
• Server features for instances are set in $CATALINA_BASE/conf/server.xml. You can change feature
status by manually editing this file. However, it is safer to use tcman.sh feature to avoid corrupting the
file with erroneous entries.
• Run tcman.sh feature when the instance is offline.
Clean up or archive server log files (clean)
Purpose
Truncate, move, or delete the log files located in the /logs directory of the core server or instance. If the server
is running, clean truncates log files to zero length. If the server is not running, clean deletes the log files from
the file system.
You have the option to save log files to a subdirectory of /logs.
Syntax
tcman.sh clean [general_options][-A]
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 919
Chapter 13: Installing and administering Private Cloud
Parameters
general_options
Specify one or more of the general TCMAN options. Run tcman.sh help clean to see which
general options are appropriate.
-A
Archive log files to a subdirectory of $CATALINA_BASE/logs. The directory is automatically named
with a month-day-year-second (MM-DD-YYYY-ss) time-stamp format. If the server is not running,
the files in $CATALINA_BASE/logs are deleted.
Example
Archive the log files of acme1, an instance of the core server pashome, and save to a file:
/psc/pashome/tcman.sh clean -I acme1 -A
Display server instances (instances)
Purpose
Show the names and locations of the instances created from the PAS installed in $CATALINA_HOME by
displaying the contents of the file where instances are registered for tracking.
By default, instances are registered for tracking $CATALINA_HOME/conf/instances.{windows|.unix}.
The file name extension indicates the OS platform where the PAS server is installed.
Syntax
tcman.sh instances [general_options]
Parameters
general_options
Specify one or more of the general TCMAN options. Run tcman.sh help instances to see
which general options are appropriate.
Output format
The following is the format of the output from a TCMAN instances action:
alias-name | full-file-path | type | state
alias-name
The user-defined name for the instance.
920 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
PAS command line reference
full-file-path
The location, in the OS file system, of the instance's root directory.
type
The designation of the server instance type (for example: instance, service, . . .).
state
An indication of the instance's validity. OK is returned for a valid server and invalid is returned for
a corrupted or non-existant server.
Example
Display the instances of the core server installed in /psc/pashome:
/psc/pashome/bin/tcman.sh instances
acme1 | /psc/wrk/acme1 | instance | ok
acme2 | /psc/wrk/acme2 | instance | ok
Notes
• By default, instances are registered when you execute a $CATALINA_HOME/bin/tcman{.sh|.bat}
create action, which automatically adds instance entries to an instances file. TCMAN removes instance
entries from the file when you execute a delete action.
You can manually add or remove instance entries from instances by using the register or unregister
actions.
• By default, the name and location of the file where instances are registered is
$CATALINA_HOME/conf/instances.{windows|.unix}.
You can change the location of the instance registration file by adding and setting the psc.as.instdir
property in the appserver.properties file. Use the TCMAN config action as in the following example:
tcman.sh config '+psc.as.instdir=PATH'
where PATH is a path name or an environment variable.
You can also change the location and/or name of instance registration files by setting the environment
variables, PAS_AS_INSTANCE_DIR, and PAS_AS_INSTANCE_FILE.
Register an instance for tracking (register)
Purpose
Register an instance for tracking purposes.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 921
Chapter 13: Installing and administering Private Cloud
Note:
Instances are automatically registered for tracking when you execute a create action. You use the register
action to restart tracking on instances after tracking was stopped.
A typical use for unregistering and then re-registering an instance is to make configuration changes when
moving instances from one location (core server) to another. The register action enables tracking and also
updates the value of CATALINA_HOME in all of the executable scripts in the instance's /bin directory to refer
to the new core server.
Syntax
tcman.sh register alias_name instance_path
Parameters
alias_name
Specify a meaningful name for the instance. The alias name must be unique in the instances file.
instance_path
Specify the OS file system path to where the instance exists. This value will be expanded into a fully
qualified OS directory path and will be verified to exist.
Example
Track test1, which is an alias for the instance /psc/acme1:
/psc/pashome/bin/tcman.sh register test1 /psc/acme1
Notes
When you register an instance for tracking or create a new instance with the create command, an entry is
created in the core Progress Application Server’s $CATALINA_HOME/conf/instances.[unix|windows]
file.
The instances.[unix|windows] file is a simple text file, which can be manually edited (with care) in the
event that it becomes out of date. The format for entries is:
instance_name = base_path
An instances.unix file uses Unix OS file path syntax (forward slashes), and an instances.windows file
uses Windows OS file path syntax (backslashes) to specify base_path.
Also note that in an instances file:
• Any line starting with a pound-sign ( # ) is a comment line.
• Blank lines are skipped.
922 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
PAS command line reference
• Instance names cannot contain spaces or any of the following characters: "[ . # | ] $ ? + = { /
, }"
Stop tracking an instance (unregister)
Purpose
Stop tracking an instance by removing the instance's entry from the
$CATALINA_HOME/conf/instances.[unix|windows] file.
Note:
You use the register action to restart tracking on instances after tracking was stopped with unregister .
A typical use for unregistering and then re-registering an instance, is to make configuration changes when
moving instances from one location, or core server, to another. The register action not only enables tracking,
it also updates the value of CATALINA_HOME in all of the executable scripts in the instance's /bin directory
to refer to the new core server.
Syntax
tcman.sh unregister alias_name
Parameters
alias_name
Specify the alias name of the instance that you want to stop tracking. The alias name must exist in
an instances.[unix|windows] file.
Example
Stop tracking test1, which is an instance of /psc/pashome:
/psc/pashome/bin/tcman.sh unregister test1
Start an instance (start)
Purpose
Start an instance of a PAS, optionally in debug mode.
Syntax
tcman.sh start [general_options] [-D|-J]
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 923
Chapter 13: Installing and administering Private Cloud
Parameters
general_options
Specify one or more of the general TCMAN options. Run tcman.sh help start to see which
general options are appropriate.
-D
Start the server in Tomcat debug mode. –D overrides the –J option.
-J
Start the server in debug mode using the JDPA (Java Platform Debugger Architecture) APIs for
debugging. –J cannot be used if the –D option is specified.
Before you run a server with the –J option, you must define a port for the JDPA debugger by setting
the JDPA_ADDRESS environment variable to a unique TCP network port number.
Example
Start the server in /psc/acme1, which is an instance of the core server in /psc/pashome:
/psc/acme1/bin/tcman.sh start
Using CATALINA_BASE: /psc/acme1
Using CATALINA_HOME: /psc/pashome
Using CATALINA_TMPDIR: /psc/acme1/temp
Using JRE_HOME: /tools/linuxx86_64/java64/jdk1.7.0_02/
Using CLASSPATH: /psc/pashome/bin/bootstrap.jar:/psc/pashome/bin/tomcat-juli.jar
Using CATALINA_PID: /psc/acme1/temp/catalina.pid
Notes
• When the TCMAN utility starts the server, it verifies the creation of the OS process and then records the
server's process-id in a .pid file. The location of the .pid file is:
OS PID File Path
UNIX $CATALINA_BASE/temp/catalina-instance_name.pid
Windows $CATALINA_BASE\logs\catalina-instance_name.pid
• You can obtain the process id of a server by running the TCMAN env action.
Stop an instance (stop)
Purpose
Stop a running instance, either gracefully or forcibly.
924 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
PAS command line reference
Note: TCMAN supports stopping a server instance that is not configured with a shutdown port.
On UNIX platforms stopping the running server instance is accomplished by sending a UNIX signal to the PAS
process. Therefore, the administrator's process must have the UNIX permissions to signal the PAS process.
On Windows platforms, the instance is identified using an OS process id that is used to stop server processes.
Syntax
tcman.sh stop [general_options] [-F[-w seconds ]]
Parameters
general_options
Specify one or more of the general TCMAN options. Run tcman.sh help stop to see which
general options are appropriate.
-F
Kill the sever process if it does not stop after a default wait time (5 seconds on UNIX, 10 seconds
on Windows). Change the default wait interval by using the –w option.
-w seconds
Optionally specify the number of seconds to wait before killing a server process.
Example
Stop the server in /psc/acme1, which is an instance of the core server in /psc/pashome:
/psc/acme1/bin/tcman.sh stop
Using CATALINA_BASE: /psc/acme1
Using CATALINA_HOME: /psc/pashome
Using CATALINA_TMPDIR: /psc/acme1/temp
Using JRE_HOME: /tools/linuxx86_64/java64/jdk1.7.0_02/
Using CLASSPATH: /psc/pashome/bin/bootstrap.jar:/psc/pashome/bin/tomcat-juli.jar
Using CATALINA_PID: /psc/acme1/temp/catalina.pid
Notes
• TCMAN supports stopping a server instance that is not configured with a shutdown port.
On UNIX platforms stopping the running server instance is accomplished by sending a UNIX signal to the
PAS process. Therefore, the administrator's process must have the UNIX permissions to signal the PAS
process. On Windows platforms, the instance is identified using an OS process id that is used to stop server
processes.
The following is an example a message you would see after a forced shut down with no shut down port:
Sep 23, 2013 4:10:47 PM org.apache.catalina.startup.Catalina stopServer
SEVERE: No shutdown port configured. Shut down server through OS signal.
Server not shut down.
Killing Tomcat with the PID: 14230
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 925
Chapter 13: Installing and administering Private Cloud
• Process ids are stored in the following locations:
OS PID File Path
UNIX $CATALINA_BASE/temp/catalina-instance_name.pid
Windows $CATALINA_BASE\logs\catalina-instance_name.pid
• You can also obtain the process id of a server by running the TCMAN env action.
Display server, OS, and runtime version information (version)
Purpose
Show the Apache Tomcat runtime version and OS information for an instance.
To execute this action, the instance cannot be running
Syntax
tcman.sh version [general_options]
Parameters
general_options
Specify one or more of the general TCMAN options. Run tcman.sh help version to see which
general options are appropriate.
Example
Display the server and runtime information for acme1, an instance of the core server installed in /psc/pashome:
$: /psc/pashome/bin/tcman.sh version -I acme1
Using CATALINA_BASE: /psc/acme1
Using CATALINA_HOME: /psc/pashome
Using CATALINA_TMPDIR: /psc/acme1/temp
Using JRE_HOME: /tools/linuxx86_64/java64/jdk1.7.0_02/
Using CLASSPATH:
/psc/pashome/bin/bootstrap.jar:/users/doc/agarbacz/psc/pashome/bin/tomcat-juli.jar
Using CATALINA_PID: /psc/acme1/temp/catalina.pid
Server version: Apache Tomcat/7.0.42
Server built: Jul 2 2013 08:57:41
Server number: 7.0.42.0
OS Name: Linux
OS Version: 2.6.18-164.el5
Architecture: amd64
JVM Version: 1.7.0_02-b13
JVM Vendor: Oracle Corporation
926 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
PAS command line reference
Test a server configuration (test)
Purpose
Displays information on the configuration and environment of an instance. It also displays information about
error conditions.
The test action starts a server (instance), loads all the configuration files, and then displays information. The
instance is stopped, exiting gracefully even if there is an error condition.
To execute this action, the instance cannot be running.
Syntax
tcman.sh test [general_options]
Parameters
general_options
Specify one or more of the general TCMAN options. Run tcman.sh help test to see which
general options are appropriate.
Example
Run a test of the configuration of acme1, which is an instance of the core server installed at /psc/pashome:
$: /psc/pashome/bin/tcman.sh -I acme1 test
Using CATALINA_BASE: /psc/acme1
Using CATALINA_HOME: /psc/pashome
Using CATALINA_TMPDIR: /psc/acme1/temp
Using JRE_HOME: /tools/linuxx86_64/java64/jdk1.7.0_02/
Using CLASSPATH: /psc/pashome/bin/bootstrap.jar:/psc/pashome/bin/tomcat-juli.jar
Using CATALINA_PID: /psc/acme1/temp/catalina.pid
. . .
Notes
The test action is particularly useful for testing to verify that a server will start and run properly after you make
changes to configuration and properties files.
Register and manage an instance as a Windows service (service)
Purpose
(Windows only) Registers or unregisters an instance as a Windows service. After an instance is registered,
you can start, stop, or check the status of the service with this action.
Note: Before you register an instance as a Windows service, you must install JDK 1.8 (for example, jdk1.8.0_66)
and set the environment variable JAVA_HOME=C:\Program Files\Java\jdk1.8.0_66.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 927
Chapter 13: Installing and administering Private Cloud
Syntax
tcman.bat service [general_options]alias_name { register | unregister | start
| stop | status }
Parameters
general_options
Specify one or more of the general TCMAN options. Run tcman.bat help service to see which
general options are appropriate.
alias_name
A required parameter that specifies the name of a PAS instance that was created using tcman
create.
register
Create a new Windows service that runs the named PAS instance alias_name..
Set the PR_DISPLAYNAME and/or PR_DESCRIPTION variables to change the display name and
description of the PAS instance service that appears in the Windows Service utility (Services tab of
the Task Manager). The defaults for these variables are:
Variable Default
PR_DISPLAYNAME Progress Application Server alias_name
PR_DESCRIPTION Progress Application Server (Tomcat 7) – http://www.progress.com
Set these variables before you register the instance. For example, if you wanted to change the
defaults for oepas1:
set PR_DISPLAYNAME=PAS ROOT Server
set PR_DESCRIPTION=Progress Application Server
tcman service oepas1 register
unregister
Delete the Windows service that runs the named PAS instance alias_name
start
Start the Windows service that corresponds to the named PAS instance alias_name. The Windows
service may also be started using the Windows service console or the SC command line utility.
stop
Stop the Windows service that corresponds to the named PAS instance alias_name. The Windows
service may also be stopped using the Windows service console or the SC command line utility.
928 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
PAS command line reference
status
The registration status of the Windows service corresponding to the named PAS instance
alias_name. The Windows service's status may be monitored using the Windows service console
or SC command line utility
Example
Register the default instance oepas1 as a Windows, then start, check status, stop, and unregister:
tcman service oepas1 register
oepas1 service is registered
tcman service oepas1 start
oepas1 started
tcman service oepas1 status
Service oepas1 is running
tcman service oepas1 stop
oepas1 is stopped
tcman service oepas1 unregister
oepas1 is unregistered
Note
Be sure that the instance is not running before you attempt to register/unregister it.
Create a Tomcat worker configuration file (workers)
Purpose
Create a preliminary worker.properties file that supports the configuration of supporting servers (workers)
for a Progress Application Server (PAS) instance.
in the Apache Reference Guide, a worker is defined as an "instance that is waiting to execute servlets or any
other content on behalf of some web server." In the context of the Progress Application Server, a worker is a
server that is called by a PAS instance to perform a specific task. Typically,you would define worker instances
to manage proxies, load balancing, clusters, or status monitoring. (For links to information on this functionality,
see the Apache Tomcat Documentation Index.) There are probably other situations where you could improve
the performance of a server instance by configuring worker instances to handle specific processing tasks.
In Apache Tomcat, workers are configured in a worker.properties file. The protocol implemented for
communication between servers and workers is the Apache JServ Protocol (version 1.3, referred to as AJP13).
In TCMAN, the workers action adds the definitions of registered PAS instances to the content of the
$CATALINA_HOME/extras/workers.template file and puts the result in
$CATALINA_HOME/temp/worker.properties. The template file supplies a set of common directives that
are referenced by all of the defined PAS instances. Individual instance definitions contain only the properties
that are unique to the instance, such as the AJP13 network connection port. (See Table 15: worker.properties
example on page 931.)
The /temp/worker.properties created by the workers action is a preliminary configuration file that you
will probably need to modify to implement your deployment. See The Apache Tomcat Connector-Reference
Guide for more information about configuring workers.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 929
Chapter 13: Installing and administering Private Cloud
Syntax
$CATALINA_HOME/tcman.sh workers [general_options] [worker_list]
Parameters
general_options
Specify one or more of the general TCMAN options. Run tcman.sh help worker to see which
general options are appropriate.
worker_list
A comma separated list of instance names and/or keywords. The keywords are:
status Include an instance that has been implemented as a status server
lb Include an instance that has been implemented as a load balance server
home Include the CATALINA_HOME core server
all Include all registered instances
If no worker_list is specified, the default worker list (all instances registered to CATALINA_HOME)
will be added. If no instances have been created, then the default worker_list is
CATALINA_HOME.
Examples
Assume there are:
• Two registered instances (piw1 and piw2) that serve Web applications
• A Tomcat load balancer instance (jklb) that distributes the workload between piw1 and piw2
• A status instance (jkstatus) that is used to monitor the runtime status of piw1 and piw2
The following are examples of worker-lists showing various combinations of keywords and instances, and the
resulting content in $CATALINA_HOME/temp/worker.properties:
Table 14: worker-list keywords
worker-list Resulting content in worker.properties
blank Default entries from worker.template plus entries for piw1 and piw2
piw1 Default entries from worker.template plus an entry for piw1
all Default entries from worker.template plus entries for piw1 and piw2
home Default entries from worker.template plus an entry for core server
(CATALINA_HOME)
930 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
PAS command line reference
worker-list Resulting content in worker.properties
home, all Default entries from worker.template plus an entry for core server,
(CATALINA_HOME), and entries for for piw1 and piw2
lb, status Default entries from worker.template plus entries for jklb, jstatus, piw1,
and piw2
Note: When no registered instance is specified, all registered instances are
automatically included.
lb, status, home, all Default entries from worker.template plus entries for jklb, jstatus, the
core server (CATALINA_HOME),piw1, and piw2
The following is an example workers.properties file that includes entries for instances piw1 and piw2:
Table 15: worker.properties example
# worker properties for instances rooted at U:\vobs\dlc\servers\pasw
# build date: 03/24/2014 11:09:23
# List of worker server instances
worker.list=piw1,piw2
#
# Global properties
#
# worker.maintain=60
#
# Common worker properties referenced by individual workers
#
worker.common.type=ajp13
worker.common.host=${psc.as.host.name}
worker.common.socket_timeout=10
worker.common.connect_timeout=10000
worker.common.socket_keepalive=true
worker.common.ping_mode=I
worker.common.ping_timeout=10000
worker.common.connect_timeout=0
worker.common.retry_interval=100
worker.common.recovery_options=7
# worker.common.connection_ping_interval=10000
# worker.common.fail_on_status=0# worker.common.max_packet_size=8192
# worker.common.recover_time=60
# properties for alias piw1 with jvmRoute piw1
worker.piw1.port=9996
worker.piw1.reference=worker.common
# properties for alias piw2 with jvmRoute piw2
worker.piw2.port=9996
worker.piw2.reference=worker.common
Notes
• The tcman workers action must be run from the PAS installation's $CATALINA_HOME/bin directory.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 931
Chapter 13: Installing and administering Private Cloud
• The /extras/workers.template file can be modified to adjust existing properties or to add additional
static information. However, you cannot replace the common properties with a unique set of properties for
each defined server.
Show Windows process information (showproc)
Purpose
(Windows only) Show information about the process specified by a process id.
Syntax
tcman.bat showproc [general_options] [process-id]
Parameters
general_options
Specify one or more of the options that can be used with any TCMAN action. Run tcman.sh help
showproc to see which general options are appropriate.
process-id
The numerical identifier of a Windows process. You can obtain a list of process ids by running the
TCMAN plist action.
932 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
PAS command line reference
Examples
Display process id's for the running instance, acme1, then specify process ids to show detailed information.
/psc/acme1/bin/tcman.bat plist -v
info: showing process ids for server with window title 13332
13332 14240
/psc/acme1/bin/tcman.bat showproc 13332
ProcesName : java
SessionId : 2
StartTime : 10/04/2015 16:29:42
Threads : 26
TotalProcessorTime : 00:00:19.9213277
UserProcessTime :
CPU (seconds) : 19.9213277
Description : Java(TM) Platform SE binary
Path : C:\Progress\OpenEdge\jdk\bin\java.exe
/psc/acme1/bin/tcman.bat showproc 14240
ProcesName : _mproapsv
SessionId : 2
StartTime : 10/04/2015 16:29:54
Threads : 7
TotalProcessorTime : 00:00:00.3744024
UserProcessTime :
CPU (seconds) : 0.3744024
Description : OpenEdge AppServer (Multi-thread)
Path : C:\Progress\OpenEdge\bin\_mproapsv.exe
General actions
This section details the actions available for displaying help and server runtime environment information.
Display help (help)
Purpose
Display summary or detailed help for all TCMAN actions, property names, and server features.
Syntax
tcman.sh help [action|property|feature]
Parameters
action
Show the syntax and options of the specified action. If no action is specified, show a list of all actions
and the general options.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 933
Chapter 13: Installing and administering Private Cloud
property
Show the settings for specified property.
feature
Show if the specified feature is enabled or disabled.
Example
Display the usage help for the create action:
$: tcman.sh help create
usage: tcman create [options] -p <http-port> [instance-opts] <new-base-path>
instance-opts:
[-s <shutdown-port>]
[-P <https-port>]
[-j <ajp13-port>]
[-W <web-apps-dir>]
[-N <inst-alias-name>]
[-U <file-owner> -G <file-group>]
general options:
-u uid:pwd pass uid and pwd for HTTP BASIC authentication
-v print verbose output
-M url override the CATALINA_BASE manager's URL with
<{http|https}://<host>:<port>/<mgr-app>
-B override CATALINA_BASE environment setting
-n debug run action but do not execute changes
Display runtime environment information (env)
Purpose
Show details about a server’s state.
Syntax
tcman.sh env [general_options] [keyword]
Parameters
general_options
Specify one or more of the general TCMAN options. Run tcman.sh help env to see which general
options are appropriate.
keyword
Specify one or more keywords that represent the name of the state that you want to view. If no
keyword is specified, then all of the state information is displayed.
Keywords include:
934 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
PAS command line reference
Keyword Description
running Indicate if a server is running ( 1 ) or not running
( 0 ).
mgrurl Display the URL of the manager application.
type Display the server type.
alias Display the server’s alias.
parent Display the pathname of the parent of an
instance.
tracking Indicate if tracking is on (1) or off ( 0).
http Display the server’s http port number.
https Display the server’s https port number.
shut Display the server’s shutdown port number. A
value of -1 indicates that there is no shutdown
port.
pid Display the server’s process id. A hyphen ( - )
indicates that the server is not running.
Example
Display all of the state information for the instance created in /psc/acme1:
/psc/acme1/bin/tscman.sh env
catalina home: /psc/pashome
catalina base: /psc/acme1
java home: /tools/linuxx86_64/java64/jdk1.7.0_02/
jre home:
manager http port: 8501
manager https port:8601
manager shut port: 8701
manager URL: http://localhost:8501/manager
config type: instance
config alias: acme1
config parent: /psc/pashome
server running: 0
instance tracking: 1
instance file: /psc/pashome/conf/instances.unix
server process-id: -
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 935
Chapter 13: Installing and administering Private Cloud
936 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
14
Setup and administration for ISVs
ISV accounts for both hosted and Private Cloud support white labeling functionality and give you the ability to
provision and manage customer tenants directly. A customer tenant is a virtual space that securely hosts
applications and data and provides a working environment for a set of users. This allows you to run your own
Software as a Service (SaaS) business and take advantage of the Rollbase platform for rapid development
and secure deployment of applications that meet critical business needs.
ISV features
For ISV pricing or to purchase, contact Progress. Rollbase provides the following benefits to all ISV customers:
• ISV account: Hosted Rollbase standard customers receive a special account that provides the ability to
create and manage customer tenants. This eliminates dependencies on Progress for deployment and
maintenance. Rollbase Private Cloud customers can set up any number of ISV Accounts for their own
customers.
• Custom login and password retrieval pages: ISVs with dedicated websites for their companies and
products can host their own branded pages for log in and forgotten passwords, making the use of Rollbase
transparent to end users. Any number of custom login pages can be created and hosted externally allowing
you to have different login mechanisms for each application, dedicated login pages for key customers, or
a central login for all of your customers.
• Custom Marketplace: You can set up a custom branded, private Marketplace or Application Directory
allowing your customers and prospects to view and install applications directly from their website.
• Customizable platform name: It is simple to replace Rollbase with your own product, platform or company
name.
• Customizable URLs: All default external links within the platform that point to company-hosted pages,
such as terms of service, privacy statement, etc, can be redirected to your pages. Hosted cloud ISV customers
will still see www.rollbase.com in the browser address bar. Private Cloud customers will see
www.yourdomain.com.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 937
Chapter 14: Setup and administration for ISVs
Note: Starting with Rollbase 4.0, in hosted Rollbase, Marketplace replaces the Application Directory. However,
for Rollbase Private Cloud users who have moved from earlier versions of Rollbase to Rollbase 4.0, Marketplace
is provided as an alternative to the Application Directory. Administrators of the master tenant can choose
Marketplace or Application Directory to publish and distribute their applications.
The topics in this section describe how to work with hosted Rollbase or Rollbase Private Cloud as an ISV.
For details, see the following topics:
• Getting started
• System applications
• Creating a custom login page
• Creating a page for users to retrieve passwords
• Customizing page title tags
• Using a third-party cloud service for storage
• Using the ISV Partner application
• Pushing application updates to other tenants
• Installing application updates
• Version history and rolling back
Getting started
Hosted Rollbase customers receive an ISV account that allows tenant and application management. When
the ISV account is created, you receive a welcome email from Rollbase that allows you to log in and start
creating customer tenants.
When you log in, you will want to view and modify your ISV accounts settings. And, you can change these
settings at any time. However, note that once you have customer tenants that changes made to ISV account
settings will not be applied immediately. Please contact Rollbase support if you need these to be activated
within 24 hours.
To view and modify your ISV settings:
1. From the drop-down menu next to your profile avatar, select Update Profile. The Personal Setup page
opens.
2. Click My Settings to view or modify your settings.
3. If you are a Private Cloud user, restart your servers for the recently modified changes to take effect. If you
are a hosted Rollbase user, contact Rollbase Customer Support to update the ISV settings.
In addition to the usual Rollbase user settings, you will see the ISV-specific options described in the table
below. All fields are optional.
938 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
System applications
Field Integration Name Description
ISV System Name isvSysName The name of your company. This
value will replace "Rollbase"
throughout the platform.
ISV Home Page isvHome The absolute URL to your website
to use instead of Rollbase.com.
Note: When you set an ISV Home
Page URL, Rollbase appends the
privacy and terms Web page URLs
to its footer. The privacy and terms
Web page URLs created for your
ISV Web page URL are <ISV Home
Page>/privacy/ and <ISV Home
Page>/terms/ respectively.
Ensure that you host your privacy
and terms Web page content in the
aforementioned URLs. Note that, if
the ISV Home page URL is not set
or is not an absolute Web address,
the privacy and terms pages do not
appear in your Home page.
ISV Login URL isvLoginUrl The URL to your custom login page
ISV Copyright isvCopyright The copyright string to use at the
bottom of all pages
ISV Support URL isvSupportUrl The URL to "Support Requests" link
to use instead of Rollbase.com
ISV Title Template isvTitleTemplate The template to use for the
<title> tag in all pages
System applications
When a Rollbase customer (i.e. tenant) is created, one or more system applications are installed. A system
application must always contain the User object, which is necessary for the functioning of every Rollbase tenant
(otherwise no users would be able to log in). System applications also include other important components
which cannot be created using regular setup functions:
• The Reports list page and menu
• The Settings object definition
• The Location, Department, and Function (LDF) object definitions
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 939
Chapter 14: Setup and administration for ISVs
Creating a custom login page
A hosted or private cloud ISV account gives you the option to create and host a custom login page. This page
can be hosted on another website to allow users to log into a Rollbase tenant.
The login page should contain forms that store the user name and password, post them to Rollbase, and handle
both successful and unsuccessful log in attempts.
Please contact Rollbase support or your account manager if you want to see examples built by some existing
hosted Rollbase or Rollbase Private Cloud customers.
Custom HTML login pages must contain a form tag that includes the following:
• An action attribute pointing to https://www.rollbase.com/router/servlet/Router
• A loginName parameter that will store the login name specified by a user
• A password parameter that will store the password specified by a user
• An act hidden parameter with a value of login
• An rt hidden parameter points to the full URL of your custom login page (this parameter stands for "return
to" and is stored as part of the user's session, so when they log out or their session expires, the user is
automatically taken back to your custom login page rather than Rollbase.com)
• An errMsg parameter is optional. If this HTTP parameter is set in the login page, URL errors, such as an
invalid user name, will be captured and displayed as error messages.
If a login is unsuccessful, Rollbase will redirect the user back to your custom login page and display the
error description set in the HTTP parameter errMsg. Progress strongly recommends that your custom login
page captures and displays this error message when it is not empty.
• An o parameter is optional. If this HTTP parameter is set in the login page URL, it will be captured and
stored in the o hidden parameter. For example, this parameter might contain the location of the first landing
page.
Creating a page for users to retrieve passwords
A hosted or private cloud ISV account gives you the option to create a page for users to retrieve forgotten
passwords. Such a page must contain HTML with a form tag satisfying the following conditions:
• An action attribute pointing to https://www.rollbase.com/router/login/forgetPassword2.jsp
• A loginName input parameter that stores the login name entered by a user
• An email input parameter that contains the email address entered by a user (must match to login name)
• An act hidden parameter with a value of forgotPassword
• An rt hidden parameter that points to the full URL of your custom login page
The following example shows a very simple password retrieval page:
<html>
<head>
<title>Custom Login Page</title>
</head>
940 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Customizing page title tags
<body>
<form action="https://www.rollbase.com/router/login/forgotPassword2.jsp" method="post"
name="theForm">
<input name="act" value="forgotPassword" type="hidden">
<input type="hidden" name="rt" value="https://www.acmeisv.com/login/customLogin.html">
<table cellpadding=0 cellspacing=0>
<tr>
<td><h2>Forgot your password?</h2><td>
<tr>
<tr>
<td colspan="2">In order for us to reset your password we need to confirm your identity.
Please enter your user name. <br>You will receive an email with a new temporary
password.</td>
</tr>
<tr>
<td nowrap><b>User Name:</b></td>
<td ><input name="loginName" size="30" type="text"></td>
</tr>
<tr>
<td nowrap><b>Email Address:</b></td>
<td ><input name="email" size="30" type="text"></td>
</tr>
<tr height='5'><td></td></tr>
<tr>
<td></td>
<td alignment='left'><input type="submit" value=" Submit " name="btnS"></td>
</tr>
</table>
</form>
</body>
</html>
Customizing page title tags
A hosted or Private Cloud ISV account gives you the option to customize the <title> tag used in application
pages that will be accessed by your customer tenants. Valid templates may include any text and the following
merge tokens that get replaced at runtime:
• {!A} — Current application name
• {!S} — ISV system name (see above)
• {!P} — Customer's subscription plan name (Solo, Professional, etc.)
• {!O} — Current object name (if any)
• {!R}—- Current record name (if any)
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 941
Chapter 14: Setup and administration for ISVs
Using a third-party cloud service for storage
By default, for ISV and Private Cloud users, Rollbase backs up data on a local drive. You can configure the
backup location from the System Console. The Storage server component specifies the backup location
value. You can set the data backup limit per backup by specifying a value for the storageUsageLimitForBkp
property in the Shared Properties. For more information on Shared Properties, see Shared Properties
on page 786.
As an alternative to local storage, you (an ISV or a Private Cloud user) can purchase and enable a third-party
cloud storage (Amazon S3 or Microsoft Azure) for your customer tenants. Cloud storage is used on a tenant
by tenant basis.
Note: Using a third party cloud service for storage can impact performance because files and images are not
served directly by Rollbase but from that third party. Progress recommends that you test the performance of
your selected storage provider before deploying cloud storage in production scenarios.
After you have enabled cloud storage, the files will be moved to your storage account in an asynchronous
mode. The tenant administrator will receive an email with summary of the moved files. After that, you can delete
the local files to save disk space.
All errors related to third-party cloud services are logged in the storage.log file. Please review this file if
you're having problems with remote storage.
See the following topics for more information:
• Using Amazon S3
• Using Microsoft Azure
Using Amazon S3
To use the Amazon S3 service for file storage, you need to have an S3 subscription and you must have at
least one bucket, your Access Key ID and Secret Access Key. You can retrieve the S3 ID and S3 Key values
for your AWS account by logging in and navigating to the Security Credentials screen.
942 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Using a third-party cloud service for storage
Enabling S3 storage
To enable Amazon S3 Storage per customer tenant, follow these steps:
1. Navigate to the ISV Partner application.
2. From the Customers List on the Customers tab, find the customer tenant for whom you want to enable
S3 storage and click Edit.
3. Scroll down to the Cloud Storage section and from the Cloud Storage drop-down, select Amazon S3.
Note: If you do not see the following fields when you edit a customer tenant, use the Design This Page
to add them from the Available Components section.
4. Enter the appropriate values in the following fields:
• S3 Bucket: The S3 bucket to use for this customer tenant.
• S3 ID: The Access Key ID assigned to your AWS account.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 943
Chapter 14: Setup and administration for ISVs
• S3 Key: The Secret Access Key associated with the Access Key ID.
5. For debugging purposes only, deselect Secure to disable SSL. For production systems, you should leave
this box unchecked.
Note: If you want to move your storage from cloud-cloud, local-cloud, or cloud-local, you must select the
Storage Move option from the Customer record More Actions menu. Then, select your desired storage option
from the New Storage drop-down list and enter the required storage details.
Using Microsoft Azure
To use the Microsoft Azure service you need to have an Azure account and you will need to specify the following
information:
• The name of your Azure account. Optionally you can add "/" followed by customer-specific text prefix which
will be added to container names used by customer. Prefixes allow storage for several customer tenants
to use the same Azure account.
• The Account Key, which plays the role of a password. Click Manage Keys at the bottom of the Azure
Management Portal page to obtain this key.
Note: Azure account and prefix names can only contain lower-case letters, digits, and hyphens "-" (but not two
hyphens in sequence). The length of the prefix cannot exceed 16 characters. The system will automatically
format specified prefix to match these Azure limitations.
The following examples illustrate how the Azure storage area relates to the specified Account Name:
Account Name Azure Name Azure Storage
rollbase Rollbase
data
template
rollbase/test Rollbase
testdata
testtemplate
rollbase/TEST_#1 Rollbase
test-1data
test-1template
Enabling Azure Storage
To enable Amazon S3 Storage per customer tenant, follow these steps:
1. Navigate to the ISV Partner application.
2. From the Customers List on the Customers tab, find the customer tenant for whom you want to enable
S3 storage and click Edit.
3. Scroll down to the Cloud Storage section and from the Cloud Storage drop-down, select Microsoft Azure.
4. Enter the appropriate values in the following fields:
• S3 Bucket: Leave this field empty, it does not apply.
• S3 ID/Account Name: The name of your Azure account.
944 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Using the ISV Partner application
• S3 Key/Account Key: The Account Key from your Azure account.
5. Select SSL if you are using secure communication to transfer data from Rollbase to Microsoft Azure. This
option is selected by default. You can disable SSL for debugging purposes.
Note: If you want to move your storage from cloud-cloud, local-cloud, or cloud-local, you must select the
Storage Move option from the Customer record More Actions menu. Then, select your desired storage option
from the New Storage drop-down list and enter the required storage details.
Using the ISV Partner application
When logging into an ISV account, you will automatically be taken to the ISV Partner application that includes
tabs for managing the following objects:
• Customers — Allows you to create and manage customer tenants.
• Published Apps — Allows you to manage applications published by customer tenants to your Application
Directory or Marketplace. Here you can edit published application information such as name and description
and choose whether or not they should appear by approving them for installation.
• Support Requests — Allows you to manage and respond to support tickets submitted by your customers
.
Sharing User object fields with customer tenants
Several fields defined on the User object in the Master tenant are designed to share important information with
ISV-managed customers. See the table in Getting started on page 938.
Private Cloud customers can define any fields to be shared between an ISV user and related customers. To
expose a field, check Make this field available for related ISV Customers checkbox on the field create or
field edit page, in the User object in the Master system. Once this is enabled, in any template or formula within
that customer tenant you can use a merge field to retrieve the value of that Master system user field.
Due to the current User caching mechanism, updates to shared fields may not be available to customers until
after the next Rollbase maintenance event (or Tomcat restart for Private Cloud customers).
Using a sandbox for development
We recommend that all ISV customers create at least one dedicated customer tenant for development purposes
(i.e. a sandbox) that applications will be published from.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 945
Chapter 14: Setup and administration for ISVs
Use sandbox customer tenants to develop and test your applications. Then use the XML publishing mechanism
described in Publishing and distributing applications on page 691 to publish your application and deploy/update
each application in your production customers.
Creating and managing customer tenants
The ISV Partner application contains Customer records to define customer tenants. To add a customer tenant,
select the Customer tab and click New Customer. Complete as much information as possible and provide
data for the first administrative user. This will initiate the tenant creation process and the administrative user
will receive a welcome email with login information and a temporary password when the tenant creation process
is completed.
To prevent users from modifying applications, create an account for yourself in each of your customer tenants
and assign the Administrator role (with all customization capabilities) to yourself rather than to your users.
You can also create a tenant with no administrative users and assign certain administrative permissions to a
custom role. See Creating a tenant with no administrative users on page 825 for more information.
To manage customer tenants, click the customer name from Customers List. The available actions include
the following:
• The Login button logs you in to a customer tenant as a super-admin, an invisible user with full access.
• From the More actions drop-down, the Login As option allows you to log in to a customer tenant as a
particular user.
• The View Logs button allows you to view system logs that are useful for troubleshooting.
• From the More actions drop-down, the Re-index option allows you to recreate the full-text search index
for that customer.
Pushing application updates to other tenants
Publishers who have a hosted ISV account, or Private Cloud customers with sufficient permissions, can push
application updates into any tenant where that particular application has already been installed.
946 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Installing application updates
Note: To minimize the impact on user sessions, try to choose a period of zero or low usage for pushing
application updates.
Here's how it works:
1. Publish your application to the Marketplace as version 1.
2. Make sure your application is approved and available for installation (edit the Published Application record
accordingly).
3. Install this application into one or more target tenants.
4. Publish updates to your application as needed. Each update will increment your app's version #.
5. Once you are ready to push updates to all of your tenants who have this app installed, go to the Published
Application view page for that app in the Master system and click Push Updates.
6. On the next page, check Override Changes if you want changes in your application to override any
customization made in target tenants (this option is always checked for fully managed applications).
7. Updates will be pushed into all target tenants who have lower version # of that application installed.
8. Pushing updates will not override changes made by administrators on target tenants.
9. If your application is fully locked, elements deleted from the original application (fields, triggers, etc.) will be
automatically deleted from target tenants. If your application is not locked, no elements will be deleted in
target tenants.
10. Updates will be scheduled for installation in an asynchronous fashion. After an update is completed in a
particular tenant, that tenant will be reloaded in memory and all users must establish new sessions (for this
reason we recommend scheduling a time to push updates during off hours for your users).
Installing application updates
After installing an application, you might need to update it periodically to the most recent version from within
the tenant (rather than pushing updates to all tenants from the master system). This can be done in one of two
ways:
• If you installed the application from the Marketplace, click Check for Updates in the application view page.
If a newer version exists, you will be prompted to install it from the application directory. For details, see
Installing and updating applications from the Marketplace App on page 125.
• If you installed an application directly from XML, obtain the new version of the Rollbase application XML
file and install it from the application view page. For details, see Installing and updating applications from
XML on page 126.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 947
Chapter 14: Setup and administration for ISVs
Version history and rolling back
When an application publisher uploads a new version of a published application to the Marketplace, Rollbase
preserves the current version of the application XML as a related Application History record. Application XML
from these history records can be viewed at any time. Rollbase administrators can also roll back a published
application to one of the older versions. The roll back action will do the following:
• Move the current application XML into a new Application History record.
• Replace the current application XML with that of the selected older version.
• Increment the current Published Application version #.
The roll back action simply creates a new version out of an older version of the application's XML, and makes
the selected version current. This action does not actually push updates to any tenants, but it does everything
to prepare you for doing this.
For example: If the current version # of your app is 3 and you choose to roll back to version 2, the result will
be version 4 which is identical to version 2. There are several reasons for treating the rolled back version as
a new app version #, primarily so that all tenants who have already installed that app are automatically aware
that there is a new version available and so that the "push updates" process rolls out the correct version of the
app. Once a roll back is done, the application XML can then be pushed to customers using the standard "Push
Updates" button (see next section).
If you do not see the Application History section as shown above when viewing a published application, edit
that page and create a new section, then drag in the Application History component from the Available
Components section in the sidebar.
948 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
15
Reference
Topics in this section describe Rollbase APIs, built-in CSSs, and field types.
For details, see the following topics:
• Server-side API
• Client-side AJAX API
• Client-side JavaScript
• Code Generator
• Metadata API and XML Reference
• Rollbase REST Methods
• Rollbase CSS Styles for the Classic UI
• Field types
• Rollbase SOAP Methods
Server-side API
This section describes server-side APIs that can be used in formulas, formula fields, and triggers. See the
heading topic for each set of APIs to see where they can be used.
Access control permissions apply to server-side APIs that view, edit, create, or delete records. Each API that
requires access control states which type of permission is required.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 949
Chapter 15: Reference
Permissions are checked for:
• The current user (Portal User or Portal Guest role for portals)
• The system role Server API
If neither the current user nor the Server API role has appropriate permissions to use the API, the API call
fails.
For APIs that require administrative permissions, only the current user's permissions are checked. The Server
API role does not allow administrative permissions.
The Server API role is required for bulk jobs and delayed triggers, because there is no user context for these
operations.
For more information about security and access permissions, see Security and access control on page 643.
API error messages
If parameters passed to API calls are incorrect or inconsistent, the Rollbase scripting engine will generate error
messages. The following table lists common error messages and suggested remedies.
Message Description
You do not have permission to perform Neither the current user nor the Server API role has
this action permission to perform requested action.
Object definition XXX not found Use a list of objects and make sure that the passed
object integration name is correct.
XXX with id 123456 not found Ensure that the passed numeric ID belongs to existing
records. In most cases use the template token for the
current record ID, record {!id}, or a related record
{!R123456}.
Field YYY not found Ensure that the field integration name is correct.
Relationship definition RRR not found Ensure that the relationship integration name is correct.
Trigger TTT not found Ensure that the trigger integration name is correct.
User with id 3456768 not found In most cases, use the token ID for the current user
{!#CURR_USER.id}
Object Definition ID 13218 is different To retrieve a record, pass pair of object name and
from required 13277 record ID. If these values do not match, an error will
result. Ensure that the object name and record ID
match.
Query API
The Rollbase Query API is available for all server-side formulas. To access these methods, use the rbv_api
system object. The order of query parameters is set and cannot be changed.
950 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Server-side API
Queries support the following syntax:
SELECT expression FROM object_name {WHERE expression} {GROUP BY
expression} {ORDER BY expression}
The SELECT statement consists of the following parts:
• SELECT lists columns or expressions to be selected (mandatory)
• Use field integration names as SQL column names. You can use expressions such as COUNT(1). Selecting
all columns with star (*) is not supported.
• FROM clause must consist of exactly one and only one object name (mandatory).
• WHERE clause includes a valid SQL expression to narrow the selection (optional). Use field integration names
as SQL column names.
• GROUP BY clause includes an expression (typically a valid field name) to group selection (optional).
• ORDER BY clause includes a valid SQL expression to order selection (optional).
Query Limitations
Only data fields with stored input values (text, decimal, etc.) can be used in a SELECT expression. Dependent
fields, such as formulas, cannot be used in query methods. A relationship (i.e. Lookup) field can be used, but
will only take the ID of the first related record--not an array of all related records. Related fields can be used if
they point to a data field.
The limitation preventing formulas from being used in the Query API can be easily bypassed in simple cases.
Consider this Formula: {!amount} * {!price}
Though you cannot use this Formula in a query directly, you can create a query such as:
SELECT SUM(amount*price)
FROM order WHERE ...
For conditions involving date fields, you can use special tokens:
• TODAY for the current time
• WEEK for 12 AM of last Sunday
• MONTH for 12 AM of 1st day of the current month
• QUARTER for 12 AM of 1st day of the current quarter
• YEAR for 12 AM of 1st day of the current year
• CURR_USER for id of the currently logged in user
You can also use built-in functions:
• #YEAR(date) returns the date's year as an integer
• #MONTH(date) returns the date's month as an integer in the range of 1 - 12
• #DAY(date) returns the date's day of the month as an integer
• #ISO(literal_string) returns the date or date/time in ISO format, which can be used in a query.
Examples: #ISO(2013-09-20T), #ISO(2013-09-20T20:05:01Z)
• #IF(expr, val1, val2) returns val1 if expr is evaluated to true, val2 otherwise.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 951
Chapter 15: Reference
The following query selects records created in the current year (starting from midnight January 1st) by current
user:
SELECT name, id FROM order WHERE
createdAt>=YEAR && createdBy=CURR_USER
Query methods do not support arithmetic operations with data tokens like view filters do. For instance, MONTH-1
does not represent the first day of the previous month. You should use a query with parameters instead. If a
query includes a Date or Date/Time column, an instance of the JavaScript Date class is returned. You can
use any JavaScript Date class methods. See selectValue() for a code example.
You can also use single-quoted integration codes for picklists and status fields in a query WHERE clause. For
example:
SELECT count(1) FROM order WHERE status='Q'
The following example reads records of where the user role integration code equals SALES:
SELECT loginName, role,
email FROM USER WHERE role = 'SALES'
0bject and field integration names are case-sensitive, while other components of an SQL query are not. When
an integration code is used to reference pick list item, status, or role in the query, the corresponding item must
actually exist and be unique. This means that two picklists in the query object cannot use the same integration
code. Otherwise, the integration code will not be resolved and will likely cause a query error.
If you query values of picklist fields, you will get numeric values corresponding to the ID of a selected item. If
you wish to receive the integration code of the selected item instead, add the #code suffix to the name of the
picklist field. Add the #value suffix to extract the display name of the selected item. The same syntax can be
used for multi-select picklists, status fields, radio Buttons etc. For example:
• SELECT my_piclkist FROM invoice WHERE id={!id): returns the numeric ID of selected item
• SELECT my_piclkist#code FROM invoice WHERE id={!id): returns the integration code of selected
item
• SELECT my_piclkist#value FROM invoice WHERE id={!id): returns the display name of selected
item
Examples of valid queries for the User object:
• Select fields for users whose name starts with ‘M': SELECT id, name, updatedAt, updatedBy FROM
USER WHERE name LIKE 'M%' ORDER BY name
• Count number of users whose name starts with ‘M': SELECT count(1) FROM USER WHERE name LIKE
'M%'
• Count number of users created or updated in current quarter: SELECT count(1) FROM USER WHERE
updatedBy>=QUARTER
• Count number of approval records for current record (identified by {!id} token): SELECT count(1)
FROM $APPROVAL WHERE approvedRecord={!id}
• Summarize amount*price expression for all records per category (picklist): SELECT
sum(amount*price), category FROM sales GROUP BY category
• Extract records created between two dates:
var d1 = new Date('2/2/2014');
var d2 = new Date('4/2/2014');
var arr = rbv_api.selectQuery(
"SELECT id, name FROM a1 WHERE createdAt BETWEEN ? AND ?", 100, d1, d2);
rbv_api.printArr(arr);
952 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Server-side API
Example of an HTML report that displays the total number of users in the system:
<html><h2>
Total users: #EVAL[ rbv_api.selectValue("SELECT COUNT(1) FROM USER") ]
</h2></html>
Although UI views do not make distinction between NULL values and 0 for numeric fields, the query API treats
NULL values and 0 differently. To mimic UI behavior you need to explicitly filter NULL values. For example:
SELECT count(1) FROM invoice WHERE amount=0 OR amount IS NULL Important Limitations
Access control applies to query methods. See Security and Access Control for more details. Passwords cannot
be retrieved through the query API due to security precautions.When applying these statements to lookup
fields, the selectQuery() and selectValue() methods return the first related ID. If you need to retrieve
all related IDs, use the getRelatedIds() method.
Some security precautions related to queries:
• 5000 characters or less
• Cannot include separators: ; \n /
• Cannot include reserved words: ALTER, BEGIN, CALL, CASCADE, DELETE, DROP, DATABASE, GRANT,
EXECUTE, INSERT, REVOKE, RENAME, SHUTDOWN, SCHEMA, UPDATE, LOGIN_NAME, PASSWORD
You can also use queries with parameters (see the method descriptions). Modifying the previous example to
use parameter results in these statements:
count(1) FROM USER WHERE name LIKE ?SELECT
Then, supply the SQL query parameter 'M%'
You can perform JavaScript calculations and then pass results to a SQL query with parameters. This technique
has a number of advantages over embedding variables directly into the text of a SQL query. To select ID of
related record you can use query similar to this:
select R1234 from
invoice where id={!id}
However please keep in mind that this query will only work for single relationships (1:1 and N:1). For multiple
relationships (1:N and N:N) result of this query is undetermined. You should use getRelatedIds() or a
template loop.
Using the UI to Design a Query
To design and test your query you can use specially designed helper page. Click the Test Query button below
formula text area to pop up that helper page. Enter your query starting with the SELECT keyword. Use merge
tokens corresponding to all available fields and objects, as well as available SQL operands and built-in functions.
To test your query, select a record of the current object type and click Test. The system will display the parsed
query and results (up to 10 rows) or error message. When you finish your testing - copy the resulting SQL
query into the body of your formula as the first parameter to one of the query methods.
The following shows an example query:
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 953
Chapter 15: Reference
rbv_api.getClassName
Warning: Support for using this method with external objects (such as those mapped to external tables,
to OpenEdge Service objects, or through a D2C connection) is a beta feature. This method is supported
in production systems, except for external objects.
Purpose
This function retrieves the name of the class to which the specified object belongs.
Syntax
rbv_api.getClassName(object)
Parameters
object
The specified object whose name of the class needs to be retrieved.
Return Value
Name of the class in string.
954 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Server-side API
Example
This example shows the retrieval of the class name for Java and native Javascript date objects.
var x = rbv_api.selectValue("select createdAt from Customer where id=?", 15872);
rbv_api.println(rbv_api.getClassName(x)); //java.util.Date
var y = new Date();
rbv_api.println(rbv_api.getClassName(y));//org.mozilla.javascript.NativeDate
rbv_api.getCount()
Warning: Support for using this method with external objects (such as those mapped to external tables,
to OpenEdge Service objects, or through a D2C connection) is a beta feature. This method is supported
in production systems, except for external objects.
Purpose
Returns the number of records in the selected view. Optionally, this method can filter by field name and value.
Syntax
rbv_api.getCount(viewId, filterName, filterValue)
Parameters
viewID
Original ID of view
filterName
Optional field integration name to filter results
filterValue
Optional field integration value to filter results
Return value
Number of records
Permissions required
View permission for the selected object type.
Example
The following example returns the total number of records in view 123456 where the Status field equals Open
(any filters imposed by the view apply as well):
var count = rbv_api.getCount("123456", "status", "Open");
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 955
Chapter 15: Reference
rbv_api.getDateInISOFromUserFormat
Warning: Support for using this method with external objects (such as those mapped to external tables,
to OpenEdge Service objects, or through a D2C connection) is a beta feature. This method is supported
in production systems, except for external objects.
Purpose
This function converts the input Date or Date/Time value from User format to ISO format. The values for Date
or Date/Time are returned in the format as selected by the user from the localization settings.
Syntax
rbv_api.getDateInISOFromUserFormat(date,format)
Parameters
date
The Date or Date/Time value to be returned.
format
The format of the date to be returned. To convert input value into Date format, enter Date and to
convert input value into Date/Time format, enter DateTime in the format parmeter.
Return Value
Date in ISO format
Example
In the given user profile setting for Date Format as Thursday, August 21, 2014 and Date/Time format
as Aug 21, 2014, 10:00:00 AM GMT+5:30, the output result is shown below:
var d = rbv_api.selectValue("select updatedAt from server where id=?", 120104);
rbv_api.println("d="+d); // Tue Jul 03 14:38:15 IST 2018
var d1 = rbv_api.getDateInISOFromUserFormat(d,"date");
rbv_api.println("d1="+d1);// 2018-07-03
var d2 = rbv_api.getDateInISOFromUserFormat(d,"datetime");
rbv_api.println("d2="+d2); // 2018-07-03T09:08:15Z
rbv_api.getDateInUserFormatFromISO
Warning: Support for using this method with external objects (such as those mapped to external tables,
to OpenEdge Service objects, or through a D2C connection) is a beta feature. This method is supported
in production systems, except for external objects.
956 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Server-side API
Purpose
This function converts the input Date or Date/Time value from ISO format to User format. The values for Date
or Date/Time are returned in the format as selected by the user from the localization settings.
Syntax
rbv_api.getDateInUserFormatFromISO(date,format)
Parameters
date
The Date or Date/Time value to be returned.
format
The format of the date to be returned. To convert input value into Date format, enter Date and to
convert input value into Date/Time format, enter DateTime in the format parmeter.
Return Value
Date in User format
Example
In the given user profile setting for Date Format as Thursday, August 21, 2014 and Date/Time format
as Aug 21, 2014, 10:00:00 AM GMT+5:30, the output result is shown below:
var d1 = rbv_api.selectValue("select updatedAt from server where id=?", 120104);
rbv_api.println("d1="+d1); // Tue Jul 03 14:38:15 IST 2018
var x1 =rbv_api.getDateInUserFormatFromISO(d1,"date");
rbv_api.println("x1="+x1); // Tuesday, July 3, 2018
var x2 =rbv_api.getDateInUserFormatFromISO(d1,"datetime");
rbv_api.println("x2="+x2); // Jul 3, 2018, 2:38:15 PM IST
rbv_api.selectQuery()
Warning: Support for using this method with external objects (such as those mapped to external tables
or through a D2C connection) is a beta feature. This method is supported in production systems, except
for external objects.
Purpose
Runs an SQL SELECT query and returns results as a 2D-array. For Private Cloud customers, the maximum
number of rows to return can be configured: see MaxReqsInQuery parameter in the description of the Shared
Properties on page 786 file.
The SELECT query used in this method consists of the following parts:
• The SELECT statement expects columns or expressions to be selected (mandatory). Use the field integration
names as SQL column names. You can use expressions such as COUNT(1). You cannot use * to retrieve
all columns.
• The FROM clause must consist of exactly one object name (mandatory).
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 957
Chapter 15: Reference
• The WHERE clause can include a valid SQL expression to narrow the selection (optional). Use field integration
names as SQL column names.
• The ORDER BY clause can include a valid SQL expression to order the selection (optional). Use field
integration names as SQL column names.
You can use special tokens in your queries such as:
• TODAY for current time
• WEEK for 12PM of last Sunday
• MONTH for 12PM of 1st day of current month
• QUARTER for 12PM of 1st day of current quarter
• YEAR for 12PM of 1st day of current year
• CURR_USER for id of currently logged in user
Object and Field names are case-sensitive, while other components of the SQL query are not.
Use #code suffix to fetch integration codes for picklist fields rather than IDs. See Adding Logic to an Application
for more information.
Syntax
rbv_api.selectQuery (query, maxRows, arg1, arg2…)
Parameters
query
SQL SELECT query. See Query API on page 950 for examples and limitations.
maxRows
Maximum number of rows to retrieve (1-20,000 range)
args
Variable number of parameters passed to query (optional)
Return value
Query result in a 2-D array
Permissions required
View permission for the selected object type.
Example
The following example uses selectQuery() to obtain Line Item object records. The WHERE clause with the
value R8011457=? retrieves only records related to the current order. The actual ID is passed as parameter,
which is more efficient because it embeds the value directly into the query. The #code suffix for the column
category fetches the integration name instead of the ID.
var arr = rbv_api.selectQuery( "select name, amount, price,
category#code from line_item where R8011457=?", 100, {!id});
var buff = "Name, Amount, Price<br>";
for (var i=0; i<arr.length; i++)
{ buff += arr[i][0]+", "+arr[i][1]+",
958 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Server-side API
"+arr[i][2] +", "+arr[i][3]+"<br>";
}
return buff;
rbv_api.selectQuery2()
Warning: Support for using this method with external objects (such as those mapped to external tables
or through a D2C connection) is a beta feature. This method is supported in production systems, except
for external objects.
Purpose
Similar to selectQuery(),selectQuery2() runs a query and returns the results as a 2D-array. The extra
parameter, rowFrom, defines a starting point for results. This makes it possible to make several calls for objects
that contain thousands of rows of data.
The SELECT query used in this method consists of the following parts:
• The SELECT statement expects columns or expressions to be selected (mandatory). Use the field integration
names as SQL column names. You can use expressions such as COUNT(1). You cannot use * to retrieve
all columns.
• The FROM clause must consist of exactly one object name (mandatory).
• The WHERE clause can include a valid SQL expression to narrow the selection (optional). Use field integration
names as SQL column names.
• The ORDER BY clause can include a valid SQL expression to order the selection (optional). Use field
integration names as SQL column names.
You can use special tokens in your queries such as:
• TODAY for current time
• WEEK for 12PM of last Sunday
• MONTH for 12PM of 1st day of current month
• QUARTER for 12PM of 1st day of current quarter
• YEAR for 12PM of 1st day of current year
• CURR_USER for id of currently logged in user
Object and Field names are case-sensitive, while other components of the SQL query are not.
Use #code suffix to fetch integration codes for picklist fields rather than IDs. See Adding Logic to an Application
for more information.
Syntax
rbv_api.selectQuery2 (query, rowFrom, maxRows, arg1, arg2…)
Parameters
query
SQL SELECT query. See Query API on page 950 for examples and limitations.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 959
Chapter 15: Reference
rowFrom
Number of row to start output (0 based)
maxRows
Maximum number of rows to retrieve (1-20,000 range)
args
Variable number of parameters passed to query (optional)
Return value
Query result in a 2-D array
Permissions required
View permission for the selected object type.
rbv_api.selectValue()
Warning: Support for using this method with external objects (such as those mapped to external tables
or through a D2C connection) is a beta feature. This method is supported in production systems, except
for external objects.
Purpose
Runs an SQL SELECT query and returns a single value. This simplified version of rbv_api.selectQuery()
is useful for calculating sum and performing other operations on single values.
The SELECT query used in this method consists of the following parts:
• The SELECT statement expects columns or expressions to be selected (mandatory). Use the field integration
names as SQL column names. You can use expressions such as COUNT(1). You cannot use * to retrieve
all columns.
• The FROM clause must consist of exactly one object name (mandatory).
• The WHERE clause can include a valid SQL expression to narrow the selection (optional). Use field integration
names as SQL column names.
• The ORDER BY clause can include a valid SQL expression to order the selection (optional). Use field
integration names as SQL column names.
You can use special tokens in your queries such as:
• TODAY for current time
• WEEK for 12PM of last Sunday
• MONTH for 12PM of 1st day of current month
• QUARTER for 12PM of 1st day of current quarter
• YEAR for 12PM of 1st day of current year
• CURR_USER for id of currently logged in user
Object and Field names are case-sensitive, while other components of the SQL query are not.
960 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Server-side API
Use #code suffix to fetch integration codes for picklist fields rather than IDs. See Adding Logic to an Application
for more information.
Syntax
rbv_api.selectValue (query, arg1, arg2…)
Parameters
query
SQL SELECT query. See examples below and see Query API on page 950 for limitations.
args
Variable number of parameters passed to query (optional)
Return value
Query result as a single value
Permissions required
View permission for the selected object type.
Example
The following example calculates the most recent update date for a set of related records. It is used in a formula
field of type Date:
rbv_api.selectValue("SELECT updatedAt FROM related_Object
WHERE R474176={!id} order by updatedAt desc");
The following example performs the same calculation, but uses an obj_id parameter with the template token
{!id} to obtain the ID of the current record. This formula field will run the SELECT query and bring back most
recent value for the updatedAt field as a Date.
var obj_id = {!id};
var d = rbv_api.selectValue("SELECT updatedAt FROM related_Object
WHERE R474176=? order by updatedAt desc", obj_id);
The following example calculates the number of records updated in the previous month (relative to the current
date). Please note that the Verbose flag is set for debugging and query parameters are used:
rbv_api.setVerbose(true);
var d1=new Date(rbv_api.firstDayOfMonth(0));
var d2=new Date(rbv_api.firstDayOfMonth(-1));
return rbv_api.selectNumber("SELECT COUNT(1)
FROM my_object where updatedAt>=? and updatedAt<?", d2, d1);
rbv_api.selectNumber()
Warning: Support for using this method with external objects (such as those mapped to external tables
or through a D2C connection) is a beta feature. This method is supported in production systems, except
for external objects.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 961
Chapter 15: Reference
Purpose
Runs a SQL SELECT query and returns a single decimal value. It is similar to the selectValue() method.
The SELECT query used in this method consists of the following parts:
• The SELECT statement expects columns or expressions to be selected (mandatory). Use the field integration
names as SQL column names. You can use expressions such as COUNT(1). You cannot use * to retrieve
all columns.
• The FROM clause must consist of exactly one object name (mandatory).
• The WHERE clause can include a valid SQL expression to narrow the selection (optional). Use field integration
names as SQL column names.
• The ORDER BY clause can include a valid SQL expression to order the selection (optional). Use field
integration names as SQL column names.
You can use special tokens in your queries such as:
• TODAY for current time
• WEEK for 12PM of last Sunday
• MONTH for 12PM of 1st day of current month
• QUARTER for 12PM of 1st day of current quarter
• YEAR for 12PM of 1st day of current year
• CURR_USER for id of currently logged in user
Object and Field names are case-sensitive, while other components of the SQL query are not.
Use #code suffix to fetch integration codes for picklist fields rather than IDs. See Adding Logic to an Application
for more information.
Syntax
rbv_api.selectNumber (query, arg1, arg2…)
Parameters
query
SQL SELECT query. See examples below and see Query API on page 950 for limitations.
args
Variable number of parameters passed to query (optional)
Return value
Query result as a decimal number
Permissions required
View permission for the selected object type.
Example
The following example selects the value in the Total field from the most recent Order record:
return rbv_api.selectNumber("SELECT total FROM order ORDER BY updatedAt DESC");
962 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Server-side API
rbv_api.selectCustomerQuery()
Warning: Support for using this method with external objects (such as those mapped to external tables,
to OpenEdge Service objects, or through a D2C connection) is a beta feature. This method is supported
in production systems, except for external objects.
Purpose
Similar to selectQuery2(), but is called from the master server and runs on the customer tenant with the
specified ID.
Do not use this API for views.
This method throws an error if the target customer tenant does not have the queried object installed. This
method might require cache loading and might be slow.
Note: When used in a trigger on a customer object with "After Create" timing, this API should be made to run
as a delayed trigger.
Syntax
rbv_api.selectCustomerQuery (custId, query, rowFrom, maxRows, arg1, arg2…)
Parameters
custId
ID of the customer record to query
query
SQL SELECT query. See Query API on page 950 for examples and limitations.
rowFrom
Number of row to start output (0 based)
maxRows
Maximum number of rows to retrieve (1-20,000 range)
args
Variable number of parameters passed to query (optional)
Return value
Query results as a 2-D array
Permissions required
The current user must be logged into the master server. The current user or the Server API role must either
have administrative permissions or have View permission on the Customer object and on the selected object
type.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 963
Chapter 15: Reference
See Managing customer tenants on page 823 for more information about customer tenants and the master
server.
rbv_api.selectCustomerValue()
Warning: Support for using this method with external objects (such as those mapped to external tables,
to OpenEdge Service objects, or through a D2C connection) is a beta feature. This method is supported
in production systems, except for external objects.
Purpose
Similar to selectValue() returns a single value, but is called from the master server and runs on the customer
with the specified ID.
Note: When used in a trigger on a customer object with "After Create" timing, this API should be made to run
as a delayed trigger
Syntax
rbv_api.selectCustomerValue (custId, query, arg1, arg2…)
Parameters
custId
ID of the customer record to query
query
SQL SELECT query. See Query API on page 950 for examples and limitations.
args
Variable number of parameters passed to query (optional)
Return value
Query result as a single value
Permissions required
The current user must be logged into the master server. The current user or the Server API role must either
have administrative permissions or have View permission on the Customer object and on the selected object
type.
See Managing customer tenants on page 823 for more information about customer tenants and the master
server.
rbv_api.selectCustomerNumber()
Warning: Support for using this method with external objects (such as those mapped to external tables,
to OpenEdge Service objects, or through a D2C connection) is a beta feature. This method is supported
in production systems, except for external objects.
964 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Server-side API
Purpose
Same as selectNumber(), but is called from the master server and runs on the customer tenant with the
specified ID.
Note: When used in a trigger on a customer object with "After Create" timing, this API should be made to run
as a delayed trigger
Syntax
rbv_api.selectCustomerNumber (custId, query, arg1, arg2…)
Parameters
custId
ID of the customer record to query
query
SQL SELECT query. See an example below and see Query API on page 950 for examples and
limitations.
args
Variable number of parameters passed to query (optional)
Return value
Query result as a number
Permissions required
The current user must be logged into the master server. The current user or the Server API role must either
have administrative permissions or have View permission on the Customer object and on the selected object
type.
See Managing customer tenants on page 823 for more information about customer tenants and the master
server.
Example
This example fetches number of records from a User object for a customer with the ID represented by the
{!id} token:
var count = rbv_api.selectCustomerNumber({!id}, "SELECT COUNT(1) FROM USER");
rbv_api.getRelatedRecordIds()
Purpose
Returns an array of related record IDs for the specified relationship field and object record ID.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 965
Chapter 15: Reference
Syntax
rbv_api.getRelatedRecordIds(objName,relFieldName,id)
Parameters
objName
Integration name of the object.
relFieldName
Integration name of the relationship field.
id
Record ID for which related records have to be fetched.
Return Value
An array of related record IDs.
Example
var arr = rbv_api.getRelatedRecordIds("Room","R1321", {!id});
for (var k=0; k<arr.length; k++) {
var id = arr[k];
rbv_api.println("id="+id);
}
rbv_api.getRelatedIds()
Purpose
For native Rollbase objects, this method returns an array of related IDs for a specified relationship and object
record ID.
Note: For external objects (such as those mapped to external tables, to OpenEdge Service objects, or through
a D2C connection), you can use the method, rbv_api.getRelatedIds2() on page 967.
Syntax
rbv_api.getRelatedIds (relName, id)
Parameters
relName
Integration name of relationship
id
Record ID from one side of the relationship
966 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Server-side API
Return value
An array of related record IDs
Example
var arr = rbv_api.getRelatedIds("R1321", {!id});
for (var k=0; k<arr.length; k++) {
var id = arr[k];
rbv_api.println("id="+id);
}
rbv_api.getRelatedIds2()
Purpose
For external objects (such as those mapped to external tables, to OpenEdge Service objects, or through a D2C
connection), returns an array of related IDs for a specified relationship and record ID.
Note: For native Rollbase objects, you can use the method, rbv_api.getRelatedIds() on page 966.
Syntax
rbv_api.getRelatedIds2(relName, objName, Id)
Parameters
relName
Integration name of the relationship.
ObjName
Integration name of the object.
Id
Record ID from one side of the relationship.
Return value
An array of related record IDs
Example
var arr = rbv_api.getRelatedIds2("R1321", "ex_group", "{!#UID}");
rbv_api.printArr(arr);
rbv_api.getRelatedRecordFields()
Purpose
Returns an array of related record field values for the specified relationship field and object record ID.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 967
Chapter 15: Reference
Syntax
rbv_api.getRelatedRecordFields(objName,relFieldName,id,relRecordFieldName)
Parameters
objName
Integration name of the object.
relFieldName
Integration name of the relationship field.
id
Record ID for which related records have to be fetched.
relRecordFieldName
Integration name of the field whose values have to be fetched.
Return Value
Array of field values from related record field values.
Example
var values = rbv_api.getRelatedRecordFields("Room", "R1321", {!id}, "status");
for (var k=0; k<values.length; k++) {
var status = values[k];
rbv_api.println("status="+status);
}
rbv_api.getRelatedFields()
Purpose
For native Rollbase objects, returns an array of field values from related records for a given relationship and
Object ID.
Note: For external objects (such as those mapped to external tables, to OpenEdge Service objects, or through
a D2C connection), you can use the method, rbv_api.getRelatedFields2() on page 969.
Syntax
rbv_api.getRelatedFields(relName, id, fieldName)
Parameters
relName
Integration name of relationship
968 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Server-side API
id
Record ID from one side of the relationship
fieldName
Integration name of field in related object
Return value
Array of field values from related records or NULL if no related records exist.
Permissions required
View permission for the selected object type.
Example
var values = rbv_api.getRelatedFields("R1321", {!id}, "status");
for (var k=0; k<values.length; k++) {
var status = values[k];
rbv_api.println("status="+status);
}
rbv_api.getRelatedFields2()
Purpose
For external objects (such as those mapped to external tables, to OpenEdge Service objects, or through a D2C
connection), returns an array of field values from related records for a given relationship and record ID.
Note: For native Rollbase objects, you can use the method, rbv_api.getRelatedFields() on page 968.
Syntax
rbv_api.getRelatedFields2(relName, objName, Id, fieldName)
Parameters
relName
Integration name of relationship.
objName
Integration name of Object.
Id
Record ID from one side of the relationship.
fieldName
Integration name for field in related object.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 969
Chapter 15: Reference
Return value
Array of field values from related records or NULL if no related records exist.
Permissions required
View permission for the selected object type.
Example
var values = rbv_api.getRelatedFields2("R1321", "ex_group", "{!#UID}", "status");
rbv_api.printArr(arr);
rbv_api.toJSDate
Warning: Support for using this method with external objects (such as those mapped to external tables,
to OpenEdge Service objects, or through a D2C connection) is a beta feature. This method is supported
in production systems, except for external objects.
Purpose
This function converts an input Date or Date/Time value into a Javascript native object.
Syntax
rbv_api.toJSDate(dateObject)
Parameters
dateObject
The input Date or Date/Time value to be converted into a Javascript native object.
Return Value
Javascript date object.
Example
This example shows the conversion of a Date or Date/Time value into a javascript object.
var x = rbv_api.selectValue("select createdAt from Customer where id=?", 15872);
var y = rbv_api.toJSDate(x);
rbv_api.println(rbv_api.getClassName(x)); //java.util.Date
rbv_api.println("x="+x); //Thu Sep 20 12:35:44 IST 2018
rbv_api.println(rbv_api.getClassName(y)); //org.mozilla.javascript.NativeDate
rbv_api.println("y="+y); //Thu Sep 20 2018 12:35:44 GMT+0530 (IST)
970 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Server-side API
rbv_api_toJava
Warning: Support for using this method with external objects (such as those mapped to external tables,
to OpenEdge Service objects, or through a D2C connection) is a beta feature. This method is supported
in production systems, except for external objects.
Purpose
This function converts an input Date or Date/Time value into a Java object.
Syntax
rbv_api.toJava(jsObject)
Parameters
jsObject
The input Date or Date/Time value to be converted into a Java object.
Return Value
Java date object.
Example
This example shows the conversion of a Date or Date/Time value into a Java date object.
var x = new Date();
var y = rbv_api.toJava(x);
rbv_api.println(rbv_api.getClassName(x));//org.mozilla.javascript.NativeDate
rbv_api.println("x="+x); //Thu Sep 20 2018 14:57:59 GMT+0530 (IST)
rbv_api.println(rbv_api.getClassName(y)); //java.util.Date
rbv_api.println("y="+y); //Thu Sep 20 14:57:59 IST 2018
rbv_api_toJS
Warning: Support for using this method with external objects (such as those mapped to external tables,
to OpenEdge Service objects, or through a D2C connection) is a beta feature. This method is supported
in production systems, except for external objects.
Purpose
This function converts a Java object to a native Javascript object.
Syntax
rbv_api.toJS(javaObject)
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 971
Chapter 15: Reference
Parameters
javaObject
The Java object to be converted into a native Javascript object.
Return Value
Javascript native object.
rbv_api.unescapeJava(input)
Warning: Support for using this method with external objects (such as those mapped to external tables,
to OpenEdge Service objects, or through a D2C connection) is a beta feature. This method is supported
in production systems, except for external objects.
Purpose
This function returns the input after unescaping the literals.
Syntax
rbv_api.unescapeJava(input)
Parameters
input
The input string to unescape the literals.
Return Value
A new unescaped string.
Example
The below example shows the conversion of Unicode codepoints into respective characters.
var input1 = "\u041F\u043E\u0437\u0434\u0440\u0430\u0432\u043B\u0435\u043D\u0438\u044F";
var y = rbv_api.unescapeJava(input1);
rbv_api.println(y); //Поздравления
This below example shows the conversion of escape sequences into respective characters
var input2 = "X\\tY\\n\\\"Z\\\"";
var x = rbv_api.unescapeJava(input2);
rbv_api.println(x);
//X Y
//"Z"
972 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Server-side API
Object Script API
The methods described in this section are for use in Object Script triggers and support a range of programmatic
data manipulation. Use of Object Script methods requires advanced skills.
Formulas used in Object Script triggers can include other API methods and regular Rollbase template
functionality, such as loops. Object Script methods have no effect if called outside of update triggers.
Object Script Example
In this example, we need to create values for a Document Number field, based on sequential IDs where the
leading letters represent a particular document type. The types must be mixed without breaking the sequence.
For example, as objects of different document types are created, the Document Number field might contain
values such as the following:
• AAA0001
• AAA0002
• BBBG001
• AAA003
The Auto-Number field cannot be used because more than one sequence is involved. Instead, to fulfill this
requirement, try the following solution:
• Create a picklist field, doc_prefix, with values AAA, BBB etc.
• Create an integer field, seq_num, but do not add this field to any page or view.
• Use the following Object Script methods in an After Create trigger to populate the Document Number field
(read-only on pages):
// Find next sequential number
var nextNum = rbv_api.selectNumber("select MAX(seq_num)
from documents where doc_prefix='{!doc_prefix#value}'") + 1;
// Format document number
var nextStr = nextNum.toString(); while (nextStr.length < 4)
nextStr = '0'+nextStr;
var docNumber = '{!doc_prefix#value}'+nextStr;
// Record document number and sequential number
rbv_api.setFieldValue("documents", {!id}, "name", docNumber);
rbv_api.setFieldValue("documents", {!id}, "seq_num", nextNum);
rbv_api.getFieldValue()
Warning: Support for using this method with external objects (such as those mapped to external tables,
to OpenEdge Service objects, or through a D2C connection) is a beta feature. This method is supported
in production systems, except for external objects.
Purpose
This object script method returns the value of a field from an existing object record. You can access fields using
template tokens instead of this method for better performance.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 973
Chapter 15: Reference
To get integration codes for enumerated values such as picklists and status, append the #code suffix to the
fieldName parameter. For example, a fieldName value of status returns a status ID, status#code
returns the status code, status#value returns the status display name.
Formulas used in Object Script triggers can include other API methods and regular Rollbase template
functionality, such as loops. Object Script methods have no effect if called outside of update triggers.
Note: Because getFieldValue() acts on existing data, it cannot be used in a validation script, which checks
data before storing it.
Syntax
rbv_api.getFieldValue(objName, Id, fieldName)
Parameters
objName
Integration name of object
Id
ID of record
fieldName
Integration name of field to retrieve value from
Return value
Value of requested field
Permissions required
View permission for the selected object type.
Example
For regular Rollbase objects:
var x = rbv_api.getFieldValue("order", {!id}, "description");
For objects imported from an external database or OpenEdge Service:
var x = rbv_api.getFieldValue("order", '{!#UID}', "description");
rbv_api.getNumFieldValue()
Warning: Support for using this method with external objects (such as those mapped to external tables,
to OpenEdge Service objects, or through a D2C connection) is a beta feature. This method is supported
in production systems, except for external objects.
974 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Server-side API
Purpose
This Object Script method returns the numeric value of a field from an existing object record. This method is
similar to getFieldValue(), but ensures that the returned value is a number or 0 if the field has a NULL
value.
Formulas used in Object Script triggers can include other API methods and regular Rollbase template
functionality, such as loops. Object Script methods have no effect if called outside of update triggers.
Syntax
rbv_api.getNumFieldValue(objName, Id, fieldName)
Parameters
Parameter Description
objName Integration name of object
Id ID of record
fieldName Integration name of field
Return value
Value of requested field
Permissions required
View permission for the selected object type.
rbv_api.getBinaryData()
Purpose
This Object Script method returns uploaded file as a base-64 encoded string. This method only works with
native Rollbase objects.
Formulas used in Object Script triggers can include other API methods and regular Rollbase template
functionality, such as loops. Object Script methods have no effect if called outside of update triggers.
Syntax
rbv_api.getBinaryData(objName, Id, fieldName)
Parameters
Parameter Description
objName Integration name of object
Id ID of record
fieldName integration name of file upload field to retrieve value
from
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 975
Chapter 15: Reference
Return value
A base-64 encoded string or null
Permissions required
View permission for the selected object type.
rbv_api.getTextData()
Purpose
This Object Script method returns uploaded file as a plain-text string. Use only with plain-text uploaded files,
such as HTML or CSV. This method only works with native Rollbase objects.
Note: This API method works with Non-ASCII characters as well. However, if your text file contains characters
other than plain ASCII, you must ensure you save the text file as UTF-8 before uploading it.
Formulas used in Object Script triggers can include other API methods and regular Rollbase template
functionality, such as loops. Object Script methods have no effect if called outside of update triggers.
Syntax
rbv_api.getTextData(objName, Id, fieldName)
Parameters
Parameter Description
objName Integration name of object
Id ID of record
fieldName integration name of File Upload field to retrieve value
from
Return value
A plain-text string or Null
Permissions required
View permission for the selected object type.
rbv_api.isFieldEmpty()
Warning: Support for using this method with external objects (such as those mapped to external tables,
to OpenEdge Service objects, or through a D2C connection) is a beta feature. This method is supported
in production systems, except for external objects.
976 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Server-side API
Purpose
This Object Script method checks whether value of particular field is null or empty without bringing the actual
value into the formula.
Note: Because isFieldEmpty() acts on existing data, it cannot be used in a validation script, which checks
data before storing it.
Formulas used in Object Script triggers can include other API methods and regular Rollbase template
functionality, such as loops. Object Script methods have no effect if called outside of update triggers.
Syntax
rbv_api.isFieldEmpty(objName, Id, fieldName)
Parameters
objName
Integration name of object
Id
ID of record
fieldName
Integration name of file upload field to retrieve value from
Return value
true if value of a field from an existing object record is null or empty, false otherwise
Example
if (rbv_api.isFieldEmpty("order", {!id}, "description") {
do something
}
rbv_api.setFieldValue()
Warning: Support for using this method with external objects (such as those mapped to external tables,
to OpenEdge Service objects, or through a D2C connection) is a beta feature. This method is supported
in production systems, except for external objects.
Purpose
This Object Script method sets the value of a field for an existing object record. For picklists and status fields,
use integration names, since they will be valid after publishing and installing your application, unlike numeric
ids.
When called outside of a transaction scope, for instance, in a JavaScript report, the setFieldValue() method
changes the field value temporarily. The setFieldValue() method does not invoke triggers before or after
the update occurs. The reason is that this method can often be used repeatedly to update several fields and
invoking triggers on each update may result in undesired behavior.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 977
Chapter 15: Reference
Formulas used in Object Script triggers can include other API methods and regular Rollbase template
functionality, such as loops. Object Script methods have no effect if called outside of update triggers.
Syntax
rbv_api.setFieldValue(objName, Id, fieldname, newValue)
Parameters
objName
Integration name of object
Id
ID of record
fieldName
Integration name of field to set value in
newValue
Value to be set
Return value
None
Permissions required
View permission for the selected object type.
Example
The following code sets a picklist (single-selection) or radio-buttons value:
rbv_api.setFieldValue("order", {!id}, "size", "S");
The following sets a picklist (multi-selection) or group of checkboxes value:
rbv_api.setFieldValue("order", {!id}, "size",
Array("S", "M"));
An alternative use is with a comma-separated string of integration codes or numeric ids:
rbv_api.setFieldValue("order", {!id}, "size", "S,M"));
rbv_api.setBinaryFieldValue()
Purpose
This Object Script method sets the value of a file upload field using a base-64 encoded string. This method
works only with native Rollbase objects.
Formulas used in Object Script triggers can include other API methods and regular Rollbase template
functionality, such as loops. Object Script methods have no effect if called outside of update triggers.
978 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Server-side API
Syntax
rbv_api.setBinaryFieldValue(objName, Id, fieldname, encodedValue, contentType,
fileName)
Parameters
objName
Integration name of object
Id
ID of record to modify
fieldName
Integration name of the field to update
encodedValue
Base-64 encoded content of value to be set
contentType
MIME content type
fileName
Name of file to be stored
Return value
None
Permissions required
Edit permission for the selected object type.
rbv_api.setTextFieldValue()
Purpose
This Object Script method sets the value of a text field to the name of a file to be stored. This method only
works with native Rollbase objects.
Formulas used in Object Script triggers can include other API methods and regular Rollbase template
functionality, such as loops. Object Script methods have no effect if called outside of update triggers.
Syntax
rbv_api.setTextFieldValue(objName, Id, fieldname, textValue, contentType, fileName)
Parameters
objName
Integration name of object
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 979
Chapter 15: Reference
Id
ID of record to modify
fieldName
Integration name of the field to update
textValue
Plain text content of value to be set
contentType
MIME content type
fileName
Name of file to be stored
Return value
None
Permissions required
Edit permission for the selected object type.
Example
var xmlBody = "<test>TEST</test>"
rbv_api.setTextFieldValue("invoice", {!id}, "xmlField", xmlBody,
"text/xml", "invoice.xml");
rbv_api.createRecord()
Warning: Support for using this method with external objects (such as those mapped to external tables,
to OpenEdge Service objects, or through a D2C connection) is a beta feature. This method is supported
in production systems, except for external objects.
Purpose
This Object Script method creates a new object record from the values passed in. The Object Script API invokes
triggers on create, on update and on delete the same way as the Rollbase user interface does. The ID of a
newly created record is available for other triggers in update chain through the shared value,
newID_objectName, that can be retrieved using getSharedValue().
Note: This methods observes required and unique field properties. An attempt to create or update a record
without setting required fields or by violating uniqueness of field values will cause an error.
Formulas used in Object Script triggers can include other API methods and regular Rollbase template
functionality, such as loops. Object Script methods have no effect if called outside of update triggers.
980 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Server-side API
Syntax
rbv_api.createRecord(objName, arr)
Parameters
objName
Integration name of the type of object to create
arr
JavaScript array of field name/value pairs (required fields must be supplied)
Return value
Object ID of the newly created record
Permissions required
Create permission for the selected object type.
Example
The following creates a related record:
var x = new Array();
x["amount"]=1000;
x["R477842"]={!id};
x["name"]="API Created";
var newId = rbv_api.createRecord("item", x);
rbv_api.print("Created record with id: "+newId);
The following creates a Communication Log record:
var a = new Array();
a["name"] = "Next Action Changed";
a["body"] = "Test body string";
a["commParent"] = {!id};
rbv_api.createRecord("COMMLOG", a);
rbv_api.updateRecord()
Warning: Support for using this method with external objects (such as those mapped to external tables,
to OpenEdge Service objects, or through a D2C connection) is a beta feature. This method is supported
in production systems, except for external objects.
Purpose
This Object Script method updates a record. Only supply values for the fields you want to change, others fields
will remain unchanged. The Object Script API invokes triggers on create, on update and on delete the same
way as the Rollbase user interface does. The ID of a newly created record is available for other triggers in
update chain through the shared value, newID_objectName, that can be retrieved using getSharedValue().
Note: This methods observes required and unique field properties. An attempt to create or update a record
without setting required fields or by violating uniqueness of field values will cause an error.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 981
Chapter 15: Reference
Formulas used in Object Script triggers can include other API methods and regular Rollbase template
functionality, such as loops. Object Script methods have no effect if called outside of update triggers.
Syntax
rbv_api.updateRecord(objName, Id, arr)
Parameters
objName
The object integration name.
Id
The ID of the record.
arr
JavaScript array of field name/value pairs (required fields must be supplied)
Return value
None
Permissions required
Edit permission for the selected object type.
Example
The following example loops through related records and updates them:
var x;
{!#LOOP_BEGIN.R477842}
x = new Array();
x["amount"]={!R477842.amount}+100;
rbv_api.updateRecord("item", {!R477842.id}, x);
{!#LOOP_END.R477842}
rbv_api.cloneRecord()
Warning: Support for using this method with external objects (such as those mapped to external tables,
to OpenEdge Service objects, or through a D2C connection) is a beta feature. This method is supported
in production systems, except for external objects.
Purpose
This Object Script method creates a new object record from the record and values passed in. The Object Script
API invokes triggers on create, on update, and on delete the same way as the Rollbase user interface does.
The ID of a newly created record is available for other triggers in update chain through the shared value,
newID_objectName, that can be retrieved using getSharedValue().
Note: This methods observes required and unique field properties. An attempt to create or update a record
without setting required fields or by violating uniqueness of field values will cause an error.
982 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Server-side API
Formulas used in Object Script triggers can include other API methods and regular Rollbase template
functionality, such as loops. Object Script methods have no effect if called outside of update triggers.
Syntax
rbv_api.cloneRecord(objName, ID, arr)
Parameters
objName
Integration name of the type of object to create
ID
ID of the record to clone
arr
JavaScript array of field name/value pairs (required fields must be supplied)
Return value
Object ID of the newly created record
Permissions required
Create permission for the selected object type and View permission on the record to be cloned
Example
The following creates a related record:
var x = new Array();
x["amount"]=1000;
x["name"]="API Cloned";
var newId = rbv_api.cloneRecord("item", {!id}, x);
rbv_api.print("Cloned record with id: "+newId);
rbv_api.attach()
Warning: Support for using this method with external objects (such as those mapped to external tables,
to OpenEdge Service objects, or through a D2C connection) is a beta feature. This method is supported
in production systems, except for external objects.
Purpose
This Object Script method creates a relationship between two records and returns true if a new relationship
has been successfully created.
Formulas used in Object Script triggers can include other API methods and regular Rollbase template
functionality, such as loops. Object Script methods have no effect if called outside of update triggers.
Syntax
rbv_api.attach(relName, objName1, Id1, objName2, Id2)
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 983
Chapter 15: Reference
Parameters
relName
Integration name of the relationship
objName1
Integration name of the first object
Id1
ID of the first object record
objName2
Integration name of the second object
Id2
ID of the second object record
Return value
true, if association succeeded
Permissions required
Edit permission for the selected object type.
rbv_api.detach()
Warning: Support for using this method with external objects (such as those mapped to external tables,
to OpenEdge Service objects, or through a D2C connection) is a beta feature. This method is supported
in production systems, except for external objects.
Purpose
This Object Script method removes a relationship between two records.
Formulas used in Object Script triggers can include other API methods and regular Rollbase template
functionality, such as loops. Object Script methods have no effect if called outside of update triggers.
Syntax
rbv_api.detach(relName, objName1, Id1, objName2, Id2)
Parameters
relName
Integration name of the relationship
objName1
Integration name of the first object
984 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Server-side API
Id1
ID of the first Object record
objName2
Integration name of the second object
Id2
ID of the second object record
Return value
None
Permissions required
Edit permission for the selected object type.
rbv_api.runTrigger()
Warning: Support for using this method with external objects (such as those mapped to external tables,
to OpenEdge Service objects, or through a D2C connection) is a beta feature. This method is supported
in production systems, except for external objects.
Purpose
This Object Script method runs a trigger on the specified object. This method will invoke a trigger regardless
of timing options, such as On After Update. For HTTP calls, consider using sendHttpGet() or
setHttpPost() instead.
Formulas used in Object Script triggers can include other API methods and regular Rollbase template
functionality, such as loops. Object Script methods have no effect if called outside of update triggers.
Syntax
rbv_api.runTrigger(objName, Id, triggerOrigId, checkValidation, runRecursions)
Parameters
objName
Integration name of the object
Id
ID of the record on which to run the trigger
triggerOrigId
Integration name (string) or original ID (string) of the trigger
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 985
Chapter 15: Reference
checkValidation
true or false. If set to true, check validation formula before running trigger, otherwise ignore
validation formula.
runRecursions
true or false. When runRecursions is set to true, configures the trigger to run recursively,
assuming recursive properties are set on the trigger definition page. Default value is false.
Return value
None
Permissions required
Edit permission for the selected object type.
Example
rbv_api.runTrigger("Query", {!id}, "TaC4hpbwSDmjSPOHavRqJA", false, true);
rbv_api.deleteRecord()
Warning: Support for using this method with external objects (such as those mapped to external tables,
to OpenEdge Service objects, or through a D2C connection) is a beta feature. This method is supported
in production systems, except for external objects.
Purpose
This Object Script method deletes the specified record.
Formulas used in Object Script triggers can include other API methods and regular Rollbase template
functionality, such as loops. Object Script methods have no effect if called outside of update triggers.
Syntax
rbv_api.deleteRecord(objName, Id)
Parameters
objName
Integration name of object
Id
ID of record to delete
Return value
None
Permissions required
Delete permission for the selected object type.
986 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Server-side API
Example
The following example deletes a record:
rbv_api.deleteRecord("item", {!R477842.id});
rbv_api.setCreator()
Purpose
This Object Script trigger method sets the Created By field value for the selected record. This method only
works with native Rollbase objects.
Formulas used in Object Script triggers can include other API methods and regular Rollbase template
functionality, such as loops. Object Script methods have no effect if called outside of update triggers.
Syntax
rbv_api.setCreator(objName, Id, creatorName, creatorId)
Parameters
objName
The object integration name.
Id
The ID of the record.
creatorName
Integration name of the user or portal user to be set as creator
creatorId
ID of the creator record
Return value
None
Permissions required
The current user must have the Administrator role to use this method.
Example
rbv_api.setCreator("item", {!id}, "USER", 123456);
rbv_api.startApproval()
Purpose
Starts the approval process on a selected record with the Approval attribute. See Approvals on page 273 for
more information about the approval process.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 987
Chapter 15: Reference
Syntax
rbv_api.startApproval(objName, Id, actionId)
Parameters
objName
The object integration name.
Id
The ID of the record.
actionId
The original ID of the workflow action that started the approval process (can be found on the workflow
action's view page).
Return value
None.
Permissions required
The current user must have Access permission on the workflow action that starts the approval process.
Example
rbv_api.startApproval("item", {!id}, "123456");
User selection API
The methods in this section give the caller access to information about users. This includes whether an
application is installed for a particular user, and who might have viewed or flagged particular records.
rbv_api.isViewed()
Purpose
Accesses the viewed attribute of a record for a particular user. This method only works with native Rollbase
objects.
Syntax
rbv_api.isViewed(objName, Id, userId)
Parameters
objName
Integration name of object
988 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Server-side API
Id
ID of the record
userId
ID of the user who might have viewed the record
Return value
true if a record was viewed
rbv_api.setViewed()
Purpose
Sets the viewed attribute for a specified record and user. This method only works with native Rollbase objects.
Syntax
rbv_api.setViewed(objName, Id, userId, isViewed)
Parameters
objName
Integration name of object
Id
ID of record
userId
ID of the user who might have viewed the record
isViewed
true or false
Return value
None
rbv_api.isFlagged()
Purpose
Determines whether a particular user flagged a record. Tip: Use the token {!#CURR_USER.id} to retrieve
the ID of the currently logged-in user. This method only works with native Rollbase objects.
Syntax
rbv_api.isFlagged(objName, Id, userId)
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 989
Chapter 15: Reference
Parameters
objName
Integration name of object
Id
ID of record
userId
ID of the user who might have flagged the record
Return value
true if a record was flagged
rbv_api.setFlagged()
Purpose
Sets the flagged attribute for a specified record and user. This method only works with native Rollbase objects.
Syntax
rbv_api.setFlagged(objName, Id, userId, isFlagged)
Parameters
objName
Integration name of object
Id
ID of record
userId
ID of the user who might have flagged the record
isFlagged
true or false
Return value
None
rbv_api.getSelectedIds()
Warning: Support for using this method with external objects (such as those mapped to external tables,
to OpenEdge Service objects, or through a D2C connection) is a beta feature. This method is supported
in production systems, except for external objects.
990 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Server-side API
Purpose
Gets an array of record ids selected by current user using check boxes in list view.
Syntax
rbv_api.getSelectedIds(objName)
Parameters
objName
Integration name of object
Return value
Array of record IDs
Example
var arr = rbv_api.getSelectedIds("order");
var buff = '';
if (arr!=null) {
for (var k=0; k<arr.length; k++)
buff += arr[k]+', ';
}
return buff;
rbv_api.isAppInstalled()
Warning: Support for using this method with external objects (such as those mapped to external tables,
to OpenEdge Service objects, or through a D2C connection) is a beta feature. This method is supported
in production systems, except for external objects.
Purpose
Returns true if application with the given ID is installed for the current customer, false otherwise.
Syntax
rbv_api.isAppInstalled(appId)
Parameters
appId
Original ID of the application
Return value
true or false
Miscellaneous methods
The methods in this section can be used in formulas.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 991
Chapter 15: Reference
rbv_api.getIdByCode()
Warning: Support for using this method with external objects (such as those mapped to external tables,
to OpenEdge Service objects, or through a D2C connection) is a beta feature. This method is supported
in production systems, except for external objects.
Purpose
Returns the ID of a status or a picklist item with the given integration code.
Syntax
rbv_api.getIdByCode (objName, fieldName, code)
Parameters
objName
Integration name for object
fieldName
Integration name of workflow status or picklist
code
Integration name of status or picklist item
Return value
ID of item or -1
Example
var itemId = rbv_api.getIdByCode("order", "type", "S",);
rbv_api.getCodeById()
Warning: Support for using this method with external objects (such as those mapped to external tables,
to OpenEdge Service objects, or through a D2C connection) is a beta feature. This method is supported
in production systems, except for external objects.
Purpose
Returns the code of a status or a picklist item with the given ID.
Syntax
rbv_api.getCodeById(objName, fieldName, id)
992 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Server-side API
Parameters
objName
Integration name of object
fieldName
Integration name of workflow status or picklist
Return value
Code of item or null
rbv_api.getIdByOriginalId()
Purpose
Given the original ID for an entity and an entity type, returns the entity's ID.
Syntax
rbv_api.getIdByOriginalId(entityType, origId)
Parameters
entityType
A string indicating the type of entity. Can be one of "object", "field", "relationship",
"webpage", "view", "template", "report", "chart", "gauge", "trigger", "process",
"status", "action", "button", or "datamap".
origId
The original ID of the entity.
Return value
If successful, the ID of the specified entity. If no entity of the specified type with the specified original ID exists,
throws an exception.
Example
The following example prints the ID of an object definition to the console.
try {
var id = rbv_api.getIdByOriginalId("object", "7550");
rbv_api.println(id);
} catch (error) {
rbv_api.println(error);
}
After running this example successfully, the object definition's ID is printed:
150049675
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 993
Chapter 15: Reference
If no object with the specified original ID exists, the following message is printed to the console:
JavaException: com.rb.core.services.api.ApiException: Error: No object exists with
original ID - 7550
rbv_api.getPicklist()
Purpose
Returns items available for selected picklist field (including radio buttons and groups of check box fields) as a
JSON array. Each array entry has the elements name, id, and code.
Syntax
rbv_api.getPicklist (objName, fieldName, mainValueId)
Parameters
objName
The object integration name.
fieldName
The picklist field integration name.
mainValueId
The ID of the main picklist item (optional, for dependent picklists only).
Return value
A JSON array of picklist items
Example
var arr = rbv_api.getPicklist("invoice", "options", null);
for (var k=0; k<arr.length; k++) {
rbv_api.println(k+" Name: "+arr[k].name+" Code: "+arr[k].code+" ID: "+arr[k].id);
}
rbv_api.getRoleById()
Purpose
Returns information about the specified role in JSON format. Throws an exception if roleId evaluates to
Super Admin.
Syntax
rbv_api.getRoleById(roleId)
994 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Server-side API
URL Parameters
roleId
The original ID of the role.
Permissions Required
Full administrative privileges.
Response
The integration code, name, description, ID, and original ID of the role in JSON format.
rbv_api.getValueById()
Warning: Support for using this method with external objects (such as those mapped to external tables,
to OpenEdge Service objects, or through a D2C connection) is a beta feature. This method is supported
in production systems, except for external objects.
Purpose
Returns the value of a status or a picklist item with the given ID.
Syntax
rbv_api.getValueById(objName, fieldName, id)
Parameters
objName
Integration name for object
fieldName
Integration name of workflow status or picklist
id
ID of status or picklist item
Return value
Text value of item or null
Example
The following returns the value of an order type.
var itemValue = rbv_api.getValueById("order", "type", {!type#id});
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 995
Chapter 15: Reference
rbv_api.runReport()
Purpose
Runs a report and returns it as a base-64 encoded string. This method only works with native Rollbase objects.
Syntax
rbv_api.runReport(reportId, filterName, filterValue)
Parameters
reportId
The original ID of the report.
filterName
An optional field that specifies the name of the field to filter.
filterValue
Specifies a value for the field. Only records with this value will be added to the report.
Return value
Base-64 encoded string.
Example
The following example reads the order report and stores the results in the file upload field:
var reportData = rbv_api.runReport("23086", null, null);
rbv_api.setBinaryFieldValue("report", {!id}, "file",
reportData, "application/pdf", "report.pdf");
rbv_api.runTemplate()
Purpose
Runs a document template on a specified object record and returns it as a base-64 encoded string. This method
only works with native Rollbase objects.
Syntax
rbv_api.runTemplate(objName, Id, templateId)
Parameters
objName
The object integration name.
Id
The ID of the record.
996 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Server-side API
templateId
The original ID of the document template.
Return value
The template as a base-64 encoded String.
Permissions required
Edit permission for the selected object type.
rbv_api.formatUsingMask()
Purpose
Formats a string containing digits as specified in the mask parameter.
Syntax
rbv_api.formatUsingMask(value, mask)
Parameters
value
The string to format
mask
The input mask, which uses # as a placeholder for a digit
Example
var x = rbv_api.formatUsingMask("123456789", "###-##-####");
Result: 123-45-6789
Date, time, and currency API
The methods in this section allow you to get and format date, number, and currency values.
rbv_api.getCurrentDate()
Purpose
Returns a string corresponding to the current date, relative to the current user's time zone. Use new Date()
to create a new instance of a JavaScript Date.
Syntax
rbv_api.getCurrentDate()
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 997
Chapter 15: Reference
Return value
Current date as a string
rbv_api.firstDayOfMonth()
Purpose
Returns a value of 12AM on the first day of the current month plus or minus the number of months specified.
Syntax
rbv_api.firstDayOfMonth(offset)
Parameters
offset
Number of months to offset the current month (positive, negative, or zero)
Return value
Date as a string.
Example
var d = new Date(rbv_api.getCurrentDate());
rbv_api.println(d);
var d1 = new Date(rbv_api.firstDayOfMonth(0));
rbv_api.println(d1);
var d2 = new Date(rbv_api.firstDayOfMonth(-1));
rbv_api.println(d2);
Output:
Sat Feb 26 2012 13:00:02 GMT-0800 (PST)
Tue Feb 01 2012 00:00:00 GMT-0800 (PST)
Sat Jan 01 2012 00:00:00 GMT-0800 (PST)
rbv_api.firstDayOfQuarter()
Purpose
Returns a value of 12AM on the first day of the current quarter plus or minus the number of quarters specified.
Syntax
rbv_api.firstDayOfQuarter(offset)
Parameters
offset
Number of quarters to offset the current quarter (positive, negative, or zero)
Return value
Date as a string.
998 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Server-side API
rbv_api.firstDayOfYear()
Purpose
Returns a value of 12AM on the first day of the current year, plus or minus the number of years specified.
Syntax
rbv_api.firstDayOfYear(offset)
Parameters
offset
Number of years to offset the current year (positive, negative, or zero)
Return value
Date as a string
Example
The following example calculates first day of the current calendar year and uses Query API to sum invoice
records after that date:
var d = new Date(rbv_api.firstDayOfYear(0));
var sum = rbv_api.selectNumber("SELECT SUM(amount) FROM invoice WHERE due_date>=?", d);
rbv_api.formatDate()
Purpose
Formats a JavaScript Date class instance as specified in the pattern parameter.
Syntax
rbv_api.formatDate(date, pattern)
Parameters
date
instance of JavaScript Date class
pattern
A pattern specified using the conventions defined in the Java SimpleDateFormat class
Return value
Date formatted as a string
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 999
Chapter 15: Reference
Example
var d = rbv_api.selectValue("select updatedAt from orders where id=?", {!id});
var x = rbv_api.formatDate(d, "yyyy-MM-dd");
rbv_api.println("x="+x);
Output:
x=2012-03-12
rbv_api.formatNumber()
Purpose
Formats a decimal number to a string according to the specified parameters.
Syntax
rbv_api.formatNumber(number, decPlaces, decSeparator, thSeparator)
Parameters
number
Number to be formatted
decPlaces
Number of decimal places to be used
decSeparator
Separator to use for decimal places
thSeparator
Character separator to use for thousands
Return value
Number as a formatted string.
Example
var x = rbv_api.formatNumber(7000123.45, 2, ",", ".");
rbv_api.println("x="+x);
Output:
x=7.000.123,45
rbv_api.formatCurrency()
Purpose
Formats a currency number as a string according to the specified parameters.
Syntax
rbv_api.formatCurrency(number, currSymbol, decPlaces, decSeparator, thSeparator)
1000 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Server-side API
Parameters
number
Number to be formatted
currSymbol
Currency symbol to use in formatted string
decPlaces
Number of decimal places to be used
decSeparator
Separator to use for decimal places
thSeparator
Character separator to use for thousands
Return value
Number as a formatted string.
Example
Example:
var x = rbv_api.formatCurrency(7000123.45, "$ ", 2, ".", " ");
rbv_api.println("x="+x);
Output:
x=$ 7 000 123.45
rbv_api.getExchangeRate()
Purpose
Returns an exchange rate between two currencies on a given date.
Syntax
rbv_api.getExchangeRate(srcCode, destCode, date)
Parameters
srcCode
Currency code to convert from
destCode
Currency code to convert to
date
Date for exchange rate (Defaults to current date)
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1001
Chapter 15: Reference
Return value
Rate as a decimal number
Example
var rate = rbv_api.getExchangeRate("EUR", "USD", new Date());
rbv_api.setExchangeRate()
Purpose
Sets an exchange rate between two currencies on a given date.
Syntax
rbv_api.setExchangeRate(srcCode, destCode, rate, date)
Parameters
srcCode
Currency code to convert from
destCode
Currency code to convert to
rate
Exchange rate, a decimal value, to be used for conversion.
date
Date for exchange rate (Defaults to current date)
Return value
None
Permissions required
Requires full administrative permissions.
Example
var rate = rbv_api.setExchangeRate("EUR", "USD", 1.23, new Date());
PDF processing API
The methods in this section simplify processing of PDF documents on the Rollbase platform. For Private Cloud
installations, these methods are only available if PDF Kit software is installed.
1002 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Server-side API
rbv_api.getPDFProperty()
Purpose
Returns the specified property of the PDF document specified as a base-64 encoded string. This method only
works with native Rollbase objects.
Syntax
rbv_api.getPDFProperty(encodedValue, property)
Parameters
encodedValue
base-64 encoded string representing PDF document
Property
One of the following: TITLE, AUTHOR, CREATIONDATE, CREATOR, KEYWORDS, MODDATE,
ENCRYPTED, ERROR
Return value
Property of PDF document as a string
Example
var str = rbv_api.getBinaryData("document", {!id}, "file");
var author = rbv_api.getPDFProperty(str, 'AUTHOR');
var encrypted = rbv_api.getPDFProperty(str,'ENCRYPTED');
rbv_api.concatPDF()
Purpose
Concatenates two or more PDF documents specified as base-64 encoded strings. This method only works
with native Rollbase objects.
Syntax
rbv_api.concatPDF(encodedValue1, encodedValue2, …)
Parameters
encodedValue1
base-64 encoded string representing 1st PDF document
encodedValue2, ...
base-64 encoded string representing PDF document(s) to concatenate
Return value
Merged PDF document as a base-64 encoded string
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1003
Chapter 15: Reference
Example
var pdf1 = rbv_api.getBinaryData("document", {!id}, "pdf_file1");
var pdf2 = rbv_api.getBinaryData("document", {!id}, "pdf_file2");
var pdf3 = rbv_api.concatPDF(pdf1, pdf2);
rbv_api.setBinaryFieldValue("document", {!id}, "pdf_file3", pdf3,
"application/pdf", "merged.pdf");
Hosted file API
Rollbase hosted files include files such as images, movies, and stylesheets for a portal. The methods in this
section allow you to interact with hosted files.
rbv_api.getHostedAsText()
Purpose
Returns the content of a hosted file as a string. This method only works for text-based files such as those with
extensions of .xml, .html, and .txt. This method only works with native Rollbase objects.
Syntax
rbv_api.getHostedAsText(origId)
Parameters
origId
Original ID of hosted file
Return value
Content of hosted file as a string or NULL if file doesn't exist
rbv_api.getHostedAsBinary()
Purpose
Returns the content of a hosted file as a base-64 encoded string. This method only works with native Rollbase
objects.
Syntax
rbv_api.getHostedAsBinary(origId)
Parameters
origId
Original ID of hosted file
Return value
The content of a hosted file as a base-64 encoded string or NULL (if file does not exist).
1004 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Server-side API
HTTP API
The functions in this section can be used to send HTTP requests from server-side logic.
rbv_api.sendHttpGet()
Purpose
Sends HTTP GET requests to the specified URL and returns the HTTP response body.
Syntax
rbv_api.sendHttpGet(url,headers,charset,retryParams)
Parameters
url
URL for the GET request
headers
Optional. A String of name-value pairs specifying the HTTP Headers to be sent in the request.
charset
Optional. Preferred encoding scheme for the HTTP response. Default value is UTF-8.
retryParams
Optional. A JSON object that Includes the following mandatory retry options for trigger.
• numRetries — Number of retries allowed for a trigger. The maximum number of retries must
not exceed 3.
• retryInterval — Interval (ms) between two subsequent retries. The maximum retry timeout
value (Retry Interval * Number of retries) can be configured using MaxHttpRetryTimeoutInMins
shared.property. Default value of MaxHttpRetryTimeoutInMins is 1 min.
• statusCodes — HTTP Response codes on which retry should happen. It can be a comma
separated values of status codes as well as a range of status codes. For example, 302-400,500.
Return value
HTTP response
Example
rbv_api.sendHttpGet
("http://www.rollbase.com/master/system/ri.jsp",
"","UTF-8" ,'{ "numRetries" : "3","retryInterval" : "2000"
,"statusCodes" : "200-300,400,500"}');
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1005
Chapter 15: Reference
rbv_api.sendHttpPost()
Purpose
Sends multipart HTTP POST requests to the specified URL and returns the body of the HTTP response.
Syntax
rbv_api.sendHttpPost(url, params, headers, chunked, retryParams)
Parameters
url
A URL containing POST request.
Note: Ensure that the URL parameters contain your customer ID or login name of your Rollbase
user account.
params
An array of POST parameters in name/value pairs.
headers
An optional array of HTTP headers in name value pairs.
chunked
If set to true or omitted, HTTP POST "chunked" parameter is used.
retryParams
AN optional JSON object that includes the following mandatory retry options for trigger.
• numRetries — Number of retries allowed for a trigger. The maximum number of retries must
not exceed 3.
• retryInterval — Interval (ms) between two subsequent retries. The maximum retry timeout
value (Retry Interval * Number of retries) can be configured using MaxHttpRetryTimeoutInMins
shared.property. Default value of MaxHttpRetryTimeoutInMins is 1 min.
• statusCodes — HTTP Response codes on which retry should happen. It can be a comma
separated values of status codes as well as a range of status codes. For example, 302-400,500.
Return value
Body of HTTP response
Example
rbv_api.sendHttpPost
("http://www.rollbase.com/master/system/ri.jsp",
'{"params":"params"}',"" ,true,'{"numRetries" : "3","retryInterval" : "2000",
"statusCodes" : "200-300,400,500"}');
1006 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Server-side API
rbv_api.sendJSONRequest()
Purpose
Sends a JSON request to the specified URL and returns the HTTP response body.
Syntax
rbv_api.sendJSONRequest(url, data, method, contentType, username, password, headers,
retryParams)
Parameters
url
URL to send an HTTP request
data
Text string or a JSON object to send as a body of the request
method
HTTP method, one of GET (default), POST, PUT or DELETE
contentType
MIME content type of data. For example:
application/json; charset=UTF-8 (default)
username
Login name for BASIC authentication, by default null
password
Password for BASIC authentication, by default null
headers
Optional array of HTTP headers in name/value pairs, by default null
retryParams
Optional JSON object that includes the following mandatory retry options for trigger.
• numRetries — Number of retries allowed for a trigger. The maximum number of retries must
not exceed 3.
• retryInterval — Interval (ms) between two subsequent retries. The maximum retry timeout
value (Retry Interval * Number of retries) can be configured using MaxHttpRetryTimeoutInMins
shared.property. Default value of MaxHttpRetryTimeoutInMins is 1 min.
• statusCodes — HTTP Response codes on which retry should happen. It can be a comma
separated values of status codes as well as a range of status codes. For example, 302-400,500.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1007
Chapter 15: Reference
Return value
Body of HTTP response
Example
rbv_api.sendJSONRequest
("http://www.rollbase.com/master/system/ri.jsp",
'{"data":"data"}', "POST", "UTF-8", "admin2@1",
"welcome", "",'{ "numRetries" : "3","retryInterval" : "1000",
"statusCodes" : "200-300,400,500"}');
rbv_api.getHTTPCookie()
Purpose
Returns the value of an HTTP cookie sent to the server during a user interface-based update operation.
Syntax
rbv_api.getHTTPCookie(name)
Parameters
Parameter Description
name The name of the HTTP cookie.
Return value
The value of the HTTP cookie or Null.
Example
The following example logs the login name stored as a cookie on the Rollbase Private Cloud login page (if the
user chooses the Remember user name option when logging in):
var x = rbv_api.getHTTPCookie("loginName");
rbv_api.log("debug", "loginName="+x);
rbv_api.getHTTPParameter()
Purpose
This method returns the value of an HTTP parameter sent to the server during a UI-based update operation
from an object field or a custom HTML component.
Syntax
rbv_api.getHTTPParameter(name)
1008 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Server-side API
Parameters
name
Name of input HTML box of a UI form HTML element
Return value
HTTP parameter or null
rbv_api.sendHttpRequest
Purpose
Rollbase server-side API to provide end-users the ability to invoke RESTful web services. This API will be
available for triggers and formula.
Note: Administrators must be careful while constructing the url of the target REST service, as they should not
use tokens, for which the value can be changed by end users. By modifying tokens values, malicious users
could invoke a different REST service and potentially leak data they do not have access to.
Syntax
rbv_api.sendHttpRequest(url, method, headers, params, body, options);
Parameters
url
The REST Service URL. This function argument is mandatory.
method
The HTTP method. This function argument is mandatory. The POST, GET, PUT, and DELETE HTTP
Methods are supported.
headers
The JSON object with key-value pairs to be forwarded as HTTP Request headers.
params
The JSON object with key-value pairs, wherein, each entry denotes HTTP Request parameter name
and parameter value.
body
The request payload as a serialized string literal.
options
The JSON object with additional optional arguments as properties.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1009
Chapter 15: Reference
Property Name Description
userName On Rollbase server side, while establishing HTTP
connection to RESTful Service host, Rollbase
supports HTTP Basic Authentication. You must
pass the user-name details as this property value.
password On Rollbase server side, while establishing HTTP
connection to RESTful Service host, Rollbase
supports HTTP Basic Authentication. You must
pass password as this property value.
httpReadTimeout This property configures socket read timeout for
the HTTP connection in milliseconds. The default
value is 2 minutes. However, this can be
configured to a maximum of 8 minutes.
debug This property logs debug messages (tenant
specific) on Rollbase server-side, while relaying
service request and response.
numRetries This property sets the number of retries allowed
for a trigger. The maximum number of retries
must not exceed 3.
retryInterval This property sets the interval (ms) between two
subsequent retries. The maximum retry timeout
value (Retry Interval * Number of retries) can be
configured using
MaxHttpRetryTimeoutInMins
shared.property. Default value of
MaxHttpRetryTimeoutInMins is 1 min.
statusCodes This property mentions the HTTP Response
codes on which retry should happen. It can be a
comma separated values of status codes as well
as a range of status codes. For example,
302-400,500.
Note: This new API is a more generic version that can be leveraged for multiple use-case scenarios unlike
the existing rbv_api.sendJSONRequest, rbv_api.sendHttpGet, rbv_api.sendHttpPost server-side
APIs that are either tied to a particular payload content-type like JSON or specific to a HTTP Request method.
Limitations
HTTP Request with content-type multipart/form-data are not supported. This API primarily works with HTTP
Request and Response payload content-types like text/plain, application/xml, application/json, and so on.
Example
var resp = rbv_api.sendHttpRequest('https://jsonplaceholder.typicode.com/
posts/1',
GET',
null,
1010 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Server-side API
null,
null,
{userName:'{!#CURR_USER.lastName#value}', password: "{!#SETTINGS.API_Password}",
httpReadTimeout: 15000, debug: true, numRetries : "3",
retryInterval : "2000",statusCodes : "200-300,400,500"});
rbv_api.println('Status:'+resp.status);
if(resp.status === 200){
var userObj = JSON.parse(resp.body);
return 'User ID:'+userObj.userId;
}
else {
rbv_api.println('Error Details:'+resp.status+' '+resp.message);
}
XML processing API
The methods in this section allow you to parse XML strings. For instance, a call to an external server might
return an XML string.
rbv_api.parseXML()
Purpose
Parses an XML string and returns an instance of org.w3c.dom.Element corresponding to the XML root.
JavaScript can use all methods of this Java object. See
http://www.w3.org/2003/01/dom2-javadoc/org/w3c/dom/Element.html for more info.
Syntax
rbv_api.parseXML(xmlString)
Parameters
xmlString
An XML document as a string
Return value
Root element of an XML document
Example
var xml = "<a><b>BBB</b><c>CCC</c></a>";
var root = rbv_api.parseXML(xml);
var nodes = root.getChildNodes();
for (var k=0; k<nodes.length; k++) {
var child = nodes.item(k);
rbv_api.println("Tag="+child.getTagName());
var nodes2 = child.getChildNodes();
for (var n=0; n<nodes2.length; n++) {
var child2 = nodes2.item(n);
var x = child2.getNodeValue();
rbv_api.println("Value="+x);
}
}
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1011
Chapter 15: Reference
Output:
Tag=b
Value=BBB
Tag=c
Value=CCC
rbv_api.evalXpath()
Purpose
Parses an XML string and evaluates an XPath expression. See http://www.w3schools.com/xsl for more
information on XPath.
Syntax
rbv_api.evalXpath(xmlString, xpathExpr)
Parameters
xmlString
XML document as a string
xpathExpr
XPath expression to evaluate
Return value
Result of XPath evaluation
Example
The following example evaluates a three-node XPath.
var xmlString =
"<a><b>node one</b><c>node two</c><b>node three</b></a>";
var xpathExpr = "/a/b/text()";
var res = rbv_api.evalXpath(xmlString, xpathExpr);
for (var k=0; k<res.length; k++)
rbv_api.println("Result: "+res.item(k));
Output:
Result: [#text: node one]
Result: [#text: node three]
JSON processing API
The methods in this section allow you to parse strings into JSON objects or to convert JSON objects into strings.
rbv_api.jsonToString()
Purpose
Converts a JSON object into a text string.
1012 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Server-side API
Syntax
rbv_api.jsonToString(json)
Parameters
json
A JSON object
Return value
A text string
rbv_api.stringToJson()
Purpose
This method parses a text string into a JSON object
Syntax
rbv_api.stringToJson(str)
Parameters
str
A string value
Return value
A text string
Example
var x = {"a":"AAAA", "b":100};
var y = rbv_api.jsonToString(x);
rbv_api.println("y="+y);
var z = rbv_api.stringToJson(y);
rbv_api.println("z.a="+z.a);
rbv_api.println("z,b="+z.b);
Output:
y={"b": 100,"a": "AAAA"}
z.a=AAAA
z,b=100
Trigger to trigger API
The methods in this section are only for use with triggers. They allow you to share information among triggers.
For example, the setSharedValue() and getSharedValue() allow storing results of calculations from
one trigger and making them available for reuse in another trigger(s).
Data can be stored only using these trigger methods while the current transaction to create, update, or delete
a record is running. If you need another type of sharing, or application-level sharing rather than record-level,
consider using company-wide settings, see Using company-wide settings on page 726.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1013
Chapter 15: Reference
rbv_api.setSharedValue()
Purpose
This method must be called within a trigger. It stores a value and makes it available for subsequent triggers
through the getSharedValue() method.
Syntax
rbv_api.setSharedValue(name, value)
Parameters
name
Symbolic name for the stored value
value
stored value
Return value
None
rbv_api.getSharedValue()
Purpose
This method must be called within a trigger. It returns a value stored by the setSharedValue() method.
Syntax
rbv_api.getSharedValue(name)
Parameters
name
Symbolic name for the stored value
Return value
Shared value or null
Example
Trigger 1:
var x = rbv_api.selectNumber(...);
// Store queried value for subsequent re-use
rbv_api.setSharedValue("x", x);
Trigger 2:
// Retrieve previously stored value
var x = rbv_api.getSharedValue("x");
1014 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Server-side API
Trigger environment API
The methods in this section can be used to determine:
• The environment in which your trigger is running: UI, Portal, API, or Delayed.
• What operation is currently being performed: create, update, delete, or something else.
Each of the APIs returns false if called outside of a trigger.
rbv_api.isUI()
Purpose
Returns true if the trigger was called or a formula containing this method was invoked from a regular UI page.
Note: This method returns false if called outside of a trigger
Syntax
rbv_api.isUI()
Parameters
None
N/A
Return value
true or false
Example
if (rbv_api.isUI()) rbv_api.print("Called from UI page");
rbv_api.isPortal()
Purpose
Returns true if a trigger is called or a formula is invoked from a portal UI page.
Note: This method returns false if called outside of a trigger
Syntax
rbv_api.isPortal()
Parameters
None
N/A
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1015
Chapter 15: Reference
Return value
true or false
Example
To receive notification when a new lead record is created from portal page, but not from UI page, create an
Email notification trigger and set the condition formula to (no need to add return keyword):
rbv_api.isPortal()
rbv_api.isMobile()
Purpose
Returns true if a trigger is called from a Rollbase Mobile-Web page.
Note: This method returns false if called outside of a trigger
Syntax
rbv_api.isMobile()
Parameters
None
N/A
Return value
true or false
rbv_api.isAPI()
Purpose
Returns true if a trigger is called from a regular Web Services API or REST.
Note: This method returns false if called outside of a trigger
Syntax
rbv_api.isAPI()
Parameters
None
N/A
Return value
true or false
1016 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Server-side API
rbv_api.isDelayed()
Purpose
Returns true if this trigger is delayed and running when no user is logged in.
Note: This method returns false if called outside of a trigger
Syntax
rbv_api.isDelayed()
Parameters
None
N/A
Return value
true or false
rbv_api.isImport()
Purpose
Returns true if this trigger is running while importing records from spreadsheet.
Note: This method returns false if called outside of a trigger
Syntax
rbv_api.isImport()
Parameters
None
N/A
Return value
true or false
rbv_api.isCreate()
Purpose
Returns true if this trigger is called while creating a new record.
Note: This method returns false if called outside of a trigger
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1017
Chapter 15: Reference
Syntax
rbv_api.isCreate()
Parameters
None
N/A
Return value
true or false
Example
if (rbv_api.isCreate()) rbv_api.print("Creating a new record");
rbv_api.isUpdate()
Purpose
Returns true if trigger is called while updating an existing record.
Note: This method returns false if called outside of a trigger
Syntax
rbv_api.isUpdate()
Parameters
None
N/A
Return value
true or false
Example
if (rbv_api.isCreate()) rbv_api.print("Creating a new record");
rbv_api.isDelete()
Purpose
Returns true if trigger is called while deleting an existing record.
Note: This method returns false if called outside of a trigger
1018 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Server-side API
Syntax
rbv_api.isDelete()
Parameters
None
N/A
Return value
true or false
Example
if (rbv_api.isDelete()){rbv_api.print("Deleting a record");}
Debugging API
The methods in this section apply to debugging of server-side logic.
rbv_api.print()
Purpose
Prints text messages in the formula and trigger debugging windows. End-users will not see the messages at
runtime.
Syntax
rbv_api.print (text)
Parameters
text
Message to print in the debugging window
Return value
None
Example
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1019
Chapter 15: Reference
rbv_api.println()
Purpose
Prints text messages in the formula debugging window, adding an end-of-line "\n" symbol after the output.
End-users will not see the messages at runtime.
The print() and println() methods can also be used in JavaScript reports to generate output.
Syntax
rbv_api.println (text)
Parameters
text
message to be output
Return value
None
1020 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Server-side API
rbv_api.printARR()
Purpose
Prints the contents of a JavaScript array in the format key => value.
Syntax
rbv_api.printArr(arr)
Parameters
arr
JavaScript array to print
Return value
None
rbv_api.setVerbose()
Purpose
Sets the verbose flag for debugging formulas and triggers. Methods such as selectQuery(),
createRecord(), updateRecord(), will generate additional debugging output if this flag is set to true.
Syntax
rbv_api.setVerbose (flag)
Parameters
flag
true or false
Return value
None
rbv_api.isVerbose()
Purpose
Returns the verbose flag that can be set using the setVerbose() method.
Syntax
rbv_api.isVerbose()
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1021
Chapter 15: Reference
Parameters
NA
Not applicable
Return value
true or false
rbv_api.inArgs()
Purpose
Returns the position (0-based index) of the first argument in a variable length list of remaining arguments.
Syntax
rbv_api.inArgs(x, arg0, arg1, …)
Parameters
x
variable
args
One or more arguments
Return value
true or false
Example
rbv_api.inArgs("Z", "X", "Y", "Z") returns 2
rbv_api.inArgs("A", "X", "Y", "Z", "1") returns -1 (i.e. not found)
Log API
The methods discussed in this section enables you to log information in a log file.
rbv_api.createActivityLog()
Purpose
Creates an activity log record on an existing object record. This method only works with native Rollbase objects.
Syntax
rbv_api.createActivityLog (objName, Id, text)
1022 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Server-side API
Parameters
objName
Integration name of object
Id
ID of record
text
Text of Activity Log record
Return value
None
rbv_api.log()
Purpose
Creates an log entry in the specified system log file.
Note: The log() method can be used for debugging delayed triggers, SOAP calls, and REST calls where
UI-based debugging is unavailable.
Syntax
rbv_api.Log (logName, text)
Parameters
logName
The name of one of the system log files—webapi, rest, jobs, debug—where your log entry will
be recorded.
text
The text entry to be logged.
Return value
None
Example
var x = rbv_api.selectValue(...);
rbv_api.log("debug", "x="+x);
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1023
Chapter 15: Reference
Email API
This section describes APIs used to read email messages from external email servers using IMAP or POP3
protocols. Only secure (SSL) connection is supported.
rbv_api.openIMAP()
Purpose
Opens connection to an external email server (such as Gmail) using IMAP protocol. It must be called once
before reading data from IMAP server.
Syntax
rbv_api.openIMAP(hostName, port, userName, password, mailProps)
Parameters
hostName
The name of the external mail server.
port
The port number for an SSL connection on the external mail server (typically 993).
userName
The user's name (typically user's email address) on the external mail server.
password
The user's password on the external mail server.
mailProps
The optional array of properties to be set on the external mail server. This may be null.
Return value
None
Example
rbv_api.openIMAP("imap.gmail.com", 993, "[email protected]", password, null);
rbv_api.openPOP3()
Purpose
Opens connection to an external email server (such as Microsoft Exchange) using POP3 protocol. It must be
called once before reading data from POP3 server.
1024 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Server-side API
Syntax
rbv_api.openPOP3(hostName, port, userName, password, mailProps)
Parameters
hostName
The name of the external mail server.
port
The port number for an SSL connection on the external mail server (typically 995).
userName
The user's name (typically user's email address) on the external mail server.
password
The user's password on the external mail server.
mailProps
The optional array of properties to be set on the external mail server. This may be null.
Return value
None
Example
rbv_api.openPOP3("mail.mydomain.com", 995, "[email protected]", password, null);
rbv_api.getMailMessageCount()
Purpose
Returns the number of messages in the INBOX folder for the logged in user.
Syntax
rbv_api.getMailMessageCount()
Return value
Number of email messages.
Example
rbv_api.openPOP3("mail.mydomain.com", 995, "[email protected]", password, null);
var x = rbv_api.getMailMessageCount();
rbv_api.closeMailSession();
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1025
Chapter 15: Reference
rbv_api.getMailMessage()
Purpose
Returns the specified number of email messages from the INBOX folder of the logged in user.
Syntax
rbv_api.getMailMessage(msgNo)
Parameters
msgNo
The number of email messages.
Return value
Object representing message. The following properties are available:
• to: address “to”
• cc: address “CC”
• from: name of sender if available, else, address “from”
• fromEmail: address "from"
• subject: subject of email message
• body: body of email message as HTML
• text: body of email message as plain text
• date: date and time of email message as plain text
Example
rbv_api.openPOP3("mail.mydomain.com", 995, "[email protected]", password, null);
var m = rbv_api.getMailMessage(100);
var x = m.get("subject");
rbv_api.closeMailSession();
rbv_api.getMailMessages()
Purpose
Returns email messages based on specified start and end indexes (1-based) from the INBOX folder of the
logged in user.
Syntax
rbv_api.getMailMessages(start, end)
1026 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Server-side API
Parameters
start
The start index (1-based) of message in the INBOX folder.
end
The end index (1-based) of message in the INBOX folder.
Return value
Array of objects representing messages. See available properties in rbv_api.getMailMessage() on page 1026.
Example
rbv_api.openPOP3("mail.mydomain.com", 995, "[email protected]", password, null);
var arr = rbv_api.getMailMessages(100, 110);
for (var k=0; k<arr.length; k++) {
var m = arr[k];
rbv_api.println(m.get('subject'));
}
rbv_api.closeMailSession();
rbv_api.closeMailSession()
Purpose
Closes connection to a connected external email server.
Syntax
rbv_api.closeMailSession()
Return value
None
User session data API
The functions in this section allow you to set, retrieve, and remove custom user session data. Rollbase stores
this data as key/value pairs and it is available for the duration of the user session.
Custom user session data is useful when you want to visit multiple application pages and have each of those
pages display data related to the same record or in the same context. For example, you might store the record
name in a script component on a view page and retrieve it to filter the view in a script component on a record
list page.
You can use client-side APIs as well as server-side APIs to access the same user session data. See User
session data on page 1125 for information about client-side user session data APIs.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1027
Chapter 15: Reference
rbv_api.setSessionData()
Purpose
This function sets user session data as a key/value pair. The maximum number of key/value pairs is 50. If you
set a value for an existing key, the new value overrides the previous value. See User session data API on page
1027 for more information about user session data.
Syntax
rbv_api.setSessionData(key, value);
Parameters
key
A string that is the lookup key for user session data. The maximum length of a key is 50 characters.
value
The value associated with key. The value can be a boolean, number, string (maximum length is 1000
characters), or null (where null is the value).
Return value
The success message "Session Data set successfully" or throws exception upon error. Exception
messages include:
• Empty Key Received! — No input was passed
• Invalid Input — Input was in the wrong format
• Limit Violation. Max Allowed: 50 keys reached — User has already stored the maximum of
50 key/value pairs
Example
The following example sets a key/value pair:
try {
var key = "name1";
var value = "Joe";
var resp = rbv_api.setSessionData(key, value);
rbv_api.println(resp);
} catch (error) {
rbv_api.println(error);
}
The following example passes a null key value and results in an error:
try {
var value = "Joe";
var resp = rbv_api.setSessionData(null, value);
rbv_api.println(resp);
} catch (error) {
1028 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Server-side API
rbv_api.println(error);
}
The error information is printed to the console:
JavaException: com.rb.core.services.api.ApiException: Empty Key Received!
rbv_api.getSessionData()
Purpose
For user session data, this function returns the value for the specified key. See User session data API on page
1027 for more information about user session data.
Syntax
rbv_api.getSessionData(key);
Parameters
key
A string that is the lookup key for user session data. The maximum length of a key is 50 characters.
Return value
If successful, returns the value associated with that key. Note that you should call JSON.parse() on the response
to get the result in the correct JavaScript data type (see example below). Throws an exception if there is no
value associated with the key. Exception messages include:
• Empty key received! — No key parameter was passed
• No Mappings Set for [key] — There is no value associated with the specified key or there is no user
session data to retrieve
Example
The following example returns the value for the specified key.
try {
var key = "name1";
var resp = JSON.parse(rbv_api.getSessionData(key));
rbv_api.println(resp);
} catch (error) {
rbv_api.println(error);
}
If there is no value associated with the specified key, Rollbase throws an exception with the following string:
JavaException: java.lang.Exception: No Mappings Set for "name1"
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1029
Chapter 15: Reference
rbv_api.getAllSessionData()
Purpose
For user session data, this function returns a complete map of key/value pairs stored as user session data as
a JavaScript object. See User session data API on page 1027 for more information about user session data.
Syntax
rbv_api.getAllSessionData();
Parameters
None
Return value
If successful, returns a complete map of key/value pairs stored as user session data as a JavaScript object.
Note that you should call JSON.parse() on the response to get the result in the correct JavaScript data types
(see example below). If there is no user session data, throws an exception with the string No Custom Session
Data is Set by User.
Example
The following example returns all key/value pairs set as user session data.
try {
var resp = JSON.parse(rbv_api.getAllSessionData());
rbv_api.println(resp);
} catch (error) {
rbv_api.println(error);
}
The following is a sample response.
{"name3": "Jane", "name2": "Jim", "name1": "Joe"}
If there is no user session data, Rollbase throws an exception with the following string:
JavaException: java.lang.Exception: No Custom Session Data is Set by User
rbv_api.removeSessionData()
Purpose
For user session data, this function removes the session data for the specified key. See User session data API
on page 1027 for more information about user session data.
Syntax
rbv_api.removeSessionData(key);
1030 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Server-side API
Parameters
key
A string that is the lookup key for user session data. The maximum length of a key is 50 characters.
Return value
If successful, returns the string OK. If unsuccessful, throws an exception with one of the following messages:
• Empty key received! — No key parameter was passed
• No Mappings Set for [key] — There is no value associated with the specified key or there is no user
session data to retrieve
Example
If successful, the following example removes the user session data associated with the key "name1" and
returns the string OK.
try {
var key = "name1";
var resp = rbv_api.removeSessionData(key);
rbv_api.println(resp);
} catch (error) {
rbv_api.println(error);
}
If there is no value associated with the specified key, Rollbase throws an exception with the following string:
JavaException: java.lang.Exception: No Mappings Set for "name1"
rbv_api.removeAllSessionData()
Purpose
For user session data, this function removes all user session data. See User session data API on page 1027 for
more information about user session data.
Syntax
rbv_api.removeAllSessionData();
Parameters
None
Return value
If successful, returns the string OK.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1031
Chapter 15: Reference
Example
If successful, the following example removes all user session data and returns the string OK.
try {
var resp = rbv_api.removeAllSessionData();
rbv_api.println(resp);
} catch (error) {
rbv_api.println(error);
}
If there is no user session data, Rollbase throws an exception with the following string:
JavaException: java.lang.Exception: No Custom Session Data is Set by User
Client-side AJAX API
Topics in this section describe APIs that can be used to modify the browser-side experience. Access control
permissions apply to client-side AJAX APIs.
The current user requires access permission to execute many AJAX APIs. See each API to see which
permissions are required. If the current user does not have appropriate permissions to access the API, the API
call fails.
For more information about security and access permissions, see Security and access control on page 643.
Queries
The Rollbase AJAX Query API allows developers to run SQL SELECT queries from application and portal
pages using AJAX.
The process of performing a SELECT query using the Client-Side Query API is similar to the server-side API
described (see Server-side API on page 949).
AJAX Query API functions typically require a callback function as a parameter. This is due to the asynchronous
nature of AJAX communications. You should process results inside that callback function rather than try to use
global JavaScript variables. For complex processing consider using other functions inside callback, possibly
included in the hosted files. For information on hosted files, see Hosted files on page 547.
Consider an example of invalid API usage:
var globalcount;
rbf_selectNumber("SELECT COUNT(1) FROM USER",
function(count) { globalcount = count; } );
alert("Counter="+globalcount);
The following code will display "Counter=undefined" since the processing of query result starts before that
result is fetched. However this example will work as expected:
rbf_selectNumber("SELECT COUNT(1) FROM USER",
function(count) { alert("Counter="+count); } );
Several Query API return results as JSON arrays or single values. JSON return values include those shown
in the following table.
1032 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Client-side AJAX API
Data Type JSON Value
NULL (no value) null
Number Number
Boolean value true or false
String String
Relationship (lookup) Array of related ids
Date or Date/time Instance of JavaScript Date class
Note: The Query APIs are supported in portals.
rbf_createRecord()
Warning: Support for using this method with external objects (such as those mapped to external tables,
to OpenEdge Service objects, or through a D2C connection) is a beta feature. This method is supported
in production systems, except for external objects.
Purpose
This method creates a new record without changing the UI presentation. If an error occurred during operation
error notification procedure will be invoked. For fields that allow values in multiple languages, you can specify
those values using the fieldMap parameter. When setting field values, it is mandatory to set a field value in
the tenant's base language.
The current user must have Create permission on the selected object type to run this API.
Syntax
rbf_createRecord(objName, fieldMap, useIds, callback, useLegacyDateFormat)
Parameters
objName
The object integration name.
fieldMap
A JSON object of the form: {"fieldIntegrationName1":value1,
"fieldIntegrationName2":value2}. When setting field values for multilingual fields, each
value can be a JSON object, for example:
{"fieldIntegrationName1":{"en":"EnglishValue1","ar":""ةشغشىن,"fr":"FrenchValue1"},
"fieldIntegrationName2":{"en":"EnglishValue2","ar":""ةشغشىن,"fr":"FrenchValue2"}}
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1033
Chapter 15: Reference
useIds
If true, the API will accept numeric IDs; if false (default) the API will return integration codes for
status fields and picklists
callback
A callback function that will receive the new record ID as its parameter
useLegacyDateFormat
This optional parameter only applies to JSON output and, specifically, to Date and Date/Time fields.
If true, or if not specified, a date value is returned as a Date object. If false, a date value is returned
as a String.
Note: This API is supported in portals as well.
rbf_deleteRecord()
Warning: Support for using this method with external objects (such as those mapped to external tables,
to OpenEdge Service objects, or through a D2C connection) is a beta feature. This method is supported
in production systems, except for external objects.
Purpose
This method deletes an existing backend record without changing UI presentation. If error occurred during
operation error notification procedure will be invoked (see rbf_setErrorsCallback).
The current user must have Delete permission on the selected object type to run this API.
Syntax
rbf_deleteRecord(objName, id, callback)
Parameters
objName
The integration name of the selected Object definition
id
ID of the selected Object record
callback
A function to be executed when the operation is successful. It does not receive any parameters. This
is an optional parameter.
Note: This API is supported in portals as well.
1034 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Client-side AJAX API
rbf_getCount()
Warning: Support for using this method with external objects (such as those mapped to external tables,
to OpenEdge Service objects, or through a D2C connection) is a beta feature. This method is supported
in production systems, except for external objects.
Purpose
This function retrieves total number of records in a view. It brings info back to the page using an asynchronous
AJAX mechanism.
Syntax
rbf_getCount(viewId, callback)
Parameters
viewID
The original ID of View
callback
A callback function that will receive number of records as first parameter
Note: This API is supported in portals as well.
rbf_getCount2()
Warning: Support for using this method with external objects (such as those mapped to external tables,
to OpenEdge Service objects, or through a D2C connection) is a beta feature. This method is supported
in production systems, except for external objects.
Purpose
After applying the specified filter condition, retrieves the number of records in a view that meet that condition.
Syntax
rbf_getCount2(viewId, filterName, filterValue, callback, useLegacyDateFormat)
Parameters
viewId
The original ID of the view
filterName
Name of the filter added to existing filters.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1035
Chapter 15: Reference
filterValue
The value of the field to filter output using "equals".
callback
A function to process the specified operation and receive its result, in the XML format, as the first
argument.
useLegacyDateFormat
This optional parameter only applies to JSON output and, specifically, to Date and Date/Time fields.
If true, or if not specified, a date value is returned as a Date object. If false, a date value is returned
as a String.
Note: This API is supported in portals as well.
Example
The following example prints the number of records whose city = Austin to the console.
function my_callback(count) {
console.log("Count is: " + count);
}
rbf_getCount2(7633, "city", "Austin", my_callback);
rbf_getDateInISOFromUserFormat
Warning: Support for using this method with external objects (such as those mapped to external tables,
to OpenEdge Service objects, or through a D2C connection) is a beta feature. This method is supported
in production systems, except for external objects.
Purpose
This function converts the input Date or Date/Time value from User format to ISO format.
Syntax
rbf_getDateInISOFromUserFormat(inputDate, format, keepOffSet)
Parameters
inputDate
The Date or Date/Time value to be returned.
format
The format of the date to be returned. To convert input value into Date format, enter Date and to
convert input value into Date/Time format, enter DateTime in the format parmeter.
1036 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Client-side AJAX API
keepOffSet
This parameter is applicable only if the input value is a Date/Time value. If keepOffSetis set to
true, UTC conversions are prevented while maintaining the timezone offset. By default keepOffSet
is set to false.
Example
For the given input Date value
rbf_getDateInISOFromUserFormat("Jun 15, 2018","Date"); // Date Format
The output result is
2018-06-15
For the given input Date/Time value and the keepOffSet parameter set to true or false:
rbf_getDateInISOFromUserFormat("Jun 15, 2018","DateTime",true); // DateTime Format
The output result is
2018-06-15T00:00:00.000+05:30
rbf_getDateInISOFromUserFormat("Jun 15, 2018","DateTime",false);//DateTime format
The output result is
2018-06-14T18:30:00.000Z // UTC
rbf_getDateInUserFormatFromISO
Warning: Support for using this method with external objects (such as those mapped to external tables,
to OpenEdge Service objects, or through a D2C connection) is a beta feature. This method is supported
in production systems, except for external objects.
Purpose
This function converts an input Date or Date/Time value from ISO format to User format.
Syntax
rbf_getDateInUserFormatFromISO(inputDate, format)
Parameters
inputDate
The Date or Date/Time value to be returned.
format
The format of the date to be returned. To convert input value into Date format, enter Date and to
convert input value into Date/Time format, enter DateTime in the format parmeter.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1037
Chapter 15: Reference
Example
If the user selects MMM d, yyyy format for Date from the Localization settings as shown below:
rbf_getDateInUserFormatFromISO("2018-06-15", "Date"); // Date Format
The output result is
Jun 15, 2018
If the user selects MMM d, yyyy, h:mm:ss tt 'GMT+5:30 format for Date/Time from the Localization settings
as shown below:
rbf_getDateInUserFormatFromISO("06/24/2018, 12:00 AM", "DateTime"); //DateTime Format
The output result is
Jun 24, 2018, 12:00:00 AM GMT+5:30
rbf_getViewCount
Warning: Support for using this method with external objects (such as those mapped to external tables,
to OpenEdge Service objects, or through a D2C connection) is a beta feature. This method is supported
in production systems, except for external objects.
Purpose
This function fetches the number of records in a view, after applying filters, if any.
Syntax
rbf_getViewCount(viewId, callback, options);
Parameters
viewId
The original ID of the view.
callback
A function to process the specified operation and receive the record count as the first argument.
options
An optional JSON object that sets the values of optional arguments. The properties that this object
can take are as follows:
• filtering: The filters to be applied on the view.
"filtering": {
"dateFilters": [{
"field": "<integration_name_of_field>",
"value": "<valid_date_filter_operand>"
}],
"filters": [{
"field": "<integration_name_of_field>",
"opCode": "<valid_opCode_for_field_type>",
1038 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Client-side AJAX API
"value": "<value>"
}, {
/* Additional filters */
}],
"joinType": "OR|AND"
}
Note: The dateFilters is an array type and only one date filter is supported in this API. The
dateFilter is not counted into the MaxFilters limit.
See rbf_getViewPage() on page 1045 for more information on filtering.
If there are filters mentioned in the view definition page, the joinType is derived from the view definition page
and it ignores the joinType (if any) specified on the API call.
If there are no filters defined in the view definition page, the joinType is derived from the API call. So, it is
mandatory to specify the joinType in such a case.
Note: The total number of allowed filters (including those defined in the view definition) cannot exceed the
shared property MaxFilters (default value 5). When sorting is specified on the API call, it overrides any sort
settings on the view definition. Only 3 sort levels are allowed on the API call.
Example
The following example filters columns by amount, price, and DOB and gives the number of records in the view:
rbf_getViewCount("12345", my_callback,
{
"filtering": {
"dateFilter": [{
"field": "DOB",
"value": "WEEK-1|WEEK"
}],
"filters": [
{
"field": "amount",
"value": "1606",
"opCode": "GE"
},
{
"field": "price",
"value": "102",
"opCode": "EQ"
}
],
"joinType": "OR"
}
});
Note: This API is supported in portals as well.
rbf_getFields()
Warning: Support for using this method with external objects (such as those mapped to external tables,
to OpenEdge Service objects, or through a D2C connection) is a beta feature. This method is supported
in production systems, except for external objects.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1039
Chapter 15: Reference
Purpose
This function retrieves the values of specified fields for a selected Rollbase record. It brings information back
to the page using the asynchronous AJAX mechanism. For fields that contain values for different languages,
pass a langCode value in the options parameter to get the values in a specific language. If the field does
not allow multiple languages, or if there is no value for the specified language, the value is returned in the
tenant's base language.
Note:
To use the options parameter, it is mandatory to specify a value for useLegacyDateFormat. If the specified
language code is not configured for the tenant, an error will be thrown.
The current user must have View permission on the selected object type to run this API.
Syntax
rbf_getFields(objName, id, fields, callback, useLegacyDateFormat, options)
Parameters
objName
The object integration name.
id
ID of the selected record
fields
A comma-separated list of field integration names
callback
A callback function that will receive parameters: objName, id, an array of received values, which
can be accessed using field's integration name as a key (see example below).
useLegacyDateFormat
This optional parameter only applies to JSON output and, specifically, to Date and Date/Time fields.
If true, or if not specified, a date value is returned as a Date object. If false, a date value is returned
as a String.
options
An optional JSON object that sets the values of optional arguments. The properties that this object
can take are as follows:
• langCode to a valid two-letter ISO language code, for example, {"langCode":"es"}
• useISODateFormat to get the date or date/time values in ISO format, for example,
{"useISODateFormat":true}.
• If the date and time value is Mon Jul 30 00:01:00 IST 2018 its equivalent ISO formatted
value 2018-07-29T18:31:00Z- is returned.
1040 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Client-side AJAX API
• If the date value is Mon Jul 30 2018, its equivalent ISO formatted value 2018-07-30 is
returned.
Note:
• This API is supported in portals as well.
• If both useLegacyDateFormat and useISODateFormat are set to true, useISODateFormat is applied.
Example
The following example reads two fields from a record in Spanish:
function my_callback(objName, objId, values) {
console.log("Record name is " + values["name"] + ". Country is " +
values["country"]);
}
rbf_getFields("room", id, "name,country", my_callback, true, {"langCode":"es"});
rbf_getPage()
Warning: Support for using this method with external objects (such as those mapped to external tables,
to OpenEdge Service objects, or through a D2C connection) is a beta feature. This method is supported
in production systems, except for external objects.
Purpose
This function fetches a set of records in a view, including (optionally) dependent records. It brings info back to
the page using an asynchronous AJAX mechanism. The amount of processing and time required to get complete
results can vary widely, depending on whether it fetches related records and the number of rows you specify
per page.
For pages containing fields that allow values in multiple languages, you can use the options parameter to
specify the language in which to return the values. If the values are not available in the specified language, it
will return the values for the tenant's base language. If the specified language is not configured for the tenant,
it will throw an error. To use the options parameter, you must also provide values for the onlyViewFields
and useLegacyDateFormat parameters.
Only records on which the current user has View permission on the selected object type(s) will be fetched.
Syntax
rbf_getPage(viewId, startRow, rowsPerPage, composite, objNames, fieldList, callback,
onlyViewFields, useLegacyDateFormat, options)
Parameters
viewId
The original ID of the view
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1041
Chapter 15: Reference
startRow
The row to start fetching records from (0 by default)
rowsPerPage
The maximum number of row to fetch in one call (user-specified value by default)
composite
The depth of recursion of dependent records to fetch (0 by default)
objNames
A comma-separated list of dependent object names to fetch (use "*" for all objects - default value)
fieldList
A comma-separated list of field names to fetch (use "*" for all fields - default value)
callback
A callback function that will receive an array of fetched records as first parameter
onlyViewFields
When true, the output only includes fields in the specified view. When false, the output includes
all fields in the object definition.
useLegacyDateFormat
This optional parameter only applies to JSON output and, specifically, to Date and Date/Time fields.
If true, or if not specified, a date value is returned as a Date object. If false, a date value is returned
as a String.
options
An optional JSON object that sets the values of optional arguments. The properties that this object
can take are as follows:
• langCode to a valid two-letter ISO language code, for example, {"langCode":"es"}
• useISODateFormat to get the date or date/time values in ISO format, for example,
{"useISODateFormat":true}.
• If the date and time value is Mon Jul 30 00:01:00 IST 2018 its equivalent ISO formatted
value 2018-07-29T18:31:00Z- is returned.
• If the date value is Mon Jul 30 2018, its equivalent ISO formatted value 2018-07-30 is
returned.
Note:
• This API is supported in portals as well.
• If both useLegacyDateFormat and useISODateFormat are set to true, useISODateFormat is applied.
1042 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Client-side AJAX API
Example
The following example fetches set or rows and processes results in a loop:
function my_callback(arr) {
for (var k=0; k<arr.length; k++) {
var amount = arr[k]['amount'];
var price = arr[k] [‘price'];
// Do something...
}
}
rbf_getPage("123456", 0, 100, null, null, "amount,price", my_callback);
rbf_getPage2()
Warning: Support for using this method with external objects (such as those mapped to external tables,
to OpenEdge Service objects, or through a D2C connection) is a beta feature. This method is supported
in production systems, except for external objects.
Purpose
Similar to rbf_getPage() on page 1041, this function fetches a set of records in a view, including (optionally)
dependent records, but allows you to apply a filter to the results. It brings info back to the page using
asynchronous AJAX mechanism. The amount of processing and time required to get complete results can vary
widely, depending on whether it fetches related records and the number of rows you specify per page.
For pages containing fields that allow values in multiple languages, you can use the options parameter to
specify the language in which to return the values. If the values are not available in the specified language, it
will return the values for the tenant's base language. If the specified language is not configured for the tenant,
it will throw an error. To use the options parameter, you must also provide values for the onlyViewFields
and useLegacyDateFormat parameters.
Only records on which the current user has View permission on the selected object type(s) will be fetched.
Syntax
rbf_getPage2(viewId, startRow, rowsPerPage, composite, objNames, fieldList,
filterName, filterValue, callback, onlyViewFields, useLegacyDateFormat, options)
Parameters
viewId
The original ID of the view
startRow
The row to start fetching records from (0 by default)
rowsPerPage
The maximum number of row to fetch in one call (user-specified value by default)
composite
The depth of recursion of dependent records to fetch (0 by default)
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1043
Chapter 15: Reference
objNames
A comma-separated list of dependent object names to fetch (use "*" for all objects - default value)
fieldList
A comma-separated list of field names to fetch (use "*" for all fields - default value)
filterName
The name of field used to filter output records
filterValue
A value used for filtering in the the same format as for spreadsheet import
callback
A callback function that will receive array of fetched records as first parameter
onlyViewFields
When true, the output only includes fields in the specified view. When false, the output includes
all fields in the object definition.
useLegacyDateFormat
This optional parameter only applies to JSON output and, specifically, to Date and Date/Time fields.
If true, or if not specified, a date value is returned as a Date object. If false, a date value is returned
as a String.
options
An optional JSON object that sets the values of optional arguments. The properties that this object
can take are as follows:
• langCode to a valid two-letter ISO language code, for example, {"langCode":"es"}
• useISODateFormat to get the date or date/time values in ISO format, for example,
{"useISODateFormat":true}.
• If the date and time value is Mon Jul 30 00:01:00 IST 2018 its equivalent ISO formatted
value 2018-07-29T18:31:00Z- is returned.
• If the date value is Mon Jul 30 2018, its equivalent ISO formatted value 2018-07-30 is
returned.
Note:
• This API is supported in portals as well.
• If both useLegacyDateFormat and useISODateFormat are set to true, useISODateFormat is applied.
1044 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Client-side AJAX API
rbf_getViewPage()
Warning: Support for using this method with external objects (such as those mapped to external tables,
to OpenEdge Service objects, or through a D2C connection) is a beta feature. This method is supported
in production systems, except for external objects.
Purpose
This function fetches a set of records in a view, including (optionally) dependent records and allows you to
apply a filter to the results. It brings info back to the page using an asynchronous AJAX mechanism. The amount
of processing and time required to get complete results can vary widely, depending on whether it fetches related
records and the number of rows you specify per page.
For pages containing fields that allow values in multiple languages, you can use the options parameter to
specify the language in which to return the values. If the values are not available in the specified language, it
will return the values for the tenant's base language. If the specified language is not configured for the tenant,
it will throw an error.
Syntax
rbf_getViewPage(viewId, callback, options);
Parameters
viewId
The original ID of the view.
callback
A callback function that will receive an array of fetched records as first parameter.
options
An optional JSON object that sets the values of optional arguments. The properties that this object
can take are as follows:
• startRow: The row to start fetching records from (0 by default).
• rowsPerPage: The maximum number of row to fetch in one call (user-specified value by default).
• composite: The option to retrieve related records.
• level: The depth of recursion of dependent records (0 by default).
• objects: An array of objects where each element has two mandatory attributes – objName
and fieldList. There must be a valid value for objects if level >0.
• objName: A valid integration name of a related object. (null and * are not valid values).
• fieldList: A comma-separated list of field names to fetch for corresponding objects.
You can provide different fieldList for different related objects as part of composite. This
fieldList is independent of the view object fieldList. (null and * are not valid values).
• fieldList: A comma-separated list of field names to fetch (use "*" for all fields - default value).
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1045
Chapter 15: Reference
• useLegacyDateFormat: If true, or if not specified, a date value is returned as a Date object.
If false, a date value is returned as a String.
• filtering: The filters to be applied on the view.
"filtering": {
"dateFilter": [{
"field": "<integration_name_of_field>",
"value": "<valid_date_filter_operand>"
}],
"filters": [{
"field": "<integration_name_of_field>",
"opCode": "<valid_opCode_for_field_type>",
"value": "<value>"
}, {
/* Additional filters */
}],
"joinType": "OR|AND"
}
Note: The dateFilters is an array type and only one date filter is supported in this API. The
dateFilter is not counted into the MaxFilters limit.
• sorting: The sorting to be applied on the view.
"sorting": [{
"field": "<integration_name_of_field>",
"order": "asc(default)|desc"
}, {
"field": "<integration_name_of_field>",
"order": "asc(default)|desc"
}, {
"field": "<integration_name_of_field>",
"order": "asc(default)|desc"
}]
• langCode: A valid two-letter ISO language code, for example, {"langCode":"es"}.
• useISODateFormat to get the date or date/time values in ISO format, for example,
{"useISODateFormat":true}.
• If the date and time value is Mon Jul 30 00:01:00 IST 2018 its equivalent ISO formatted
value 2018-07-29T18:31:00Z- is returned.
• If the date value is Mon Jul 30 2018, its equivalent ISO formatted value 2018-07-30 is
returned.
If there are filters mentioned in the view definition page, the joinType is derived from the view definition page
and it ignores the joinType (if any) specified on the API call.
If there are no filters defined in the view definition page, the joinType is derived from the API call. So, it is
mandatory to specify the joinType in such a case.
Note:
• The total number of allowed filters (including those defined in the view definition) cannot exceed the shared
property MaxFilters (default value 5). When sorting is specified on the API call, it overrides any sort
settings on the view definition. Only 3 sort levels are allowed on the API call.
• If both useLegacyDateFormat and useISODateFormat are set to true, useISODateFormat is applied.
1046 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Client-side AJAX API
Special date filter can be specified like the one available in UI. The 'name' should be the integration name of
the date field. The possible value that a filter value takes is as follows.
Table 16: Date Filters
Date Filter Value: UI Date Filter Value: API
Current year YEAR|YEAR+1
Previous year YEAR-1|YEAR
Current and previous yea YEAR-1|YEAR+1
Next year YEAR+1|YEAR+2
Current quarter QUARTER|QUARTER+1
Previous quarter QUARTER-1|QUARTER
Current and previous quarter QUARTER-1|QUARTER+1
Next quarter QUARTER+1|QUARTER+2
Current month MONTH|MONTH+1
Last month MONTH-1|MONTH
Current and previous month MONTH-1|MONTH+1
Next month MONTH+1|MONTH+2
Current and next month MONTH|MONTH+2
This week WEEK|WEEK+1
Last week WEEK-1|WEEK
Next week WEEK+1|WEEK+2
Today TODAY|TODAY+1
Yesterday TODAY-1|TODAY
Tomorrow TODAY+1|TODAY+2
Last 7 days TODAY-7|TODAY
Last 30 days TODAY-30|TODAY
Last 60 days TODAY-60|TODAY
Last 90 days TODAY-90|TODAY
Next 30 days TODAY+1|TODAY+30
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1047
Chapter 15: Reference
The following table lists the different values that an opCode key can take for field types derived from UI.
Table 17: opCode Key Values
opCode Key Value
EQ equals
NEQ not equal
ST starts with
CT contains
END ends with
NCT does not contain
LT less than
GT greater than
LE less or equal
GE greater or equal
IN in array
NIN not in array
CH checked
NCH unchecked
INC including
NINC not including
NUL is null
NNUL not null
IS is
The following table lists the opCode keys that are available for different field types.
Field Types opCode Keys
Picklist, Role, Status, Process, Appraisal, Approval EQ, NEQ, IN, NIN
Relationship, User, Portal Visitor EQ, NEQ, IN, NUL, NNUL
Multi-picklist INC, NINC
1048 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Client-side AJAX API
Field Types opCode Keys
Number (Integer, etc), Date EQ, NEQ, LT, GT, LE, GE, NUL, NNUL
Time LT, GT, LE, GE, NUL, NNUL
Checkbox CH, NCH
Text EQ, NEQ, ST, END, CT, NCT, IN, NIN, NUL, NNUL
File NUL, NNUL
Note: This API is supported in portals as well.
Example
The following example filters columns by amount, price, and DOB:
rbf_getViewPage("12345", my_callback, {
"useLegacyDateFormat": false,
"startRow": 0,
"rowsPerPage": 1000,
"composite": {
"level": 1,
"objects": [{
"objName": "order",
"fieldList": "amount"
}]
},
"fieldList": "amount, price,DOB",
"filtering": {
"dateFilter": [{
"field": "DOB",
"value": "WEEK-1|WEEK"
}],
"filters": [{
"field": "amount",
"value": "1606",
"opCode": "GE"
},
{
"field": "price",
"value": "102",
"opCode": "EQ"
}
],
"joinType": "OR"
},
"sorting": [{
"field": "amount",
"order": "asc"
},
{
"field": "price",
"order": "desc"
}
],
"langCode": "es"
});
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1049
Chapter 15: Reference
rbf_getRelatedFields2()
Purpose
This function retrieves the values of the selected fields for records related to a selected Rollbase record.
For fields that allow values in multiple languages, you can specify the language in which to return values in the
options parameter. If the values are not available in the specified language, it will return the values for the
tenant's base language. If the specified language is not configured for the tenant, it will throw an error. To use
the options parameter, you must set a value for useLegacyDateFormat.
The current user must have View permission on the selected object type to run this API.
Syntax
rbf_getRelatedFields2(relName, objName, id, fieldName, callback,
useLegacyDateFormat, options)
Parameters
relName
The integration name of selected Relationship definition
objName
The integration name of selected Object definition
id
The ID of selected Object record
fieldName
The integration name of Field to retrieve (for related records)
callback
A callback function that will receive parameters: relName, id, an array of received values (one
value per related record).
useLegacyDateFormat
This optional parameter only applies to JSON output and, specifically, to Date and Date/Time fields.
If true, or if not specified, a date value is returned as a Date object. If false, a date value is returned
as a String.
options
An optional JSON object that sets the values of optional arguments. The properties that this object
can take are as follows:
• langCode to a valid two-letter ISO language code, for example, {"langCode":"es"}
• useISODateFormat to get the date or date/time values in ISO format, for example,
{"useISODateFormat":true}.
1050 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Client-side AJAX API
• If the date and time value is Mon Jul 30 00:01:00 IST 2018 its equivalent ISO formatted
value 2018-07-29T18:31:00Z- is returned.
• If the date value is Mon Jul 30 2018, its equivalent ISO formatted value 2018-07-30 is
returned.
Note:
• This API is supported in portals as well.
• If both useLegacyDateFormat and useISODateFormat are set to true, useISODateFormat is applied.
Example
The following example reads field "amount" from related records and makes these values available for
computations:
function my_callback(relName, objId, values) {
for (var i=0; i<values.length; i++) {
var amount = values[i];
// Do something...
}
}
rbf_getRelatedFields2("R12345", "obj1", id, "amount ", my_callback);
rbf_getRelatedIds()
Purpose
For native Rollbase objects, this function retrieves the ids of records related to a selected Rollbase record.
The current user must have View permission on the selected object type to run this API.
Note: For external objects (such as those mapped to external tables, to OpenEdge Service objects, or through
a D2C connection), you can use the method, rbf_getRelatedIds2() on page 1052.
Syntax
rbf_getRelatedIds(relName, id, callback)
Note: This API is supported in portals as well.
Parameters
relName
Integration name of selected Relationship definition
id
ID of selected Object record
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1051
Chapter 15: Reference
callback
A callback function that will receive parameters: relName, id, an array of related ids.
rbf_getRelatedIds2()
Purpose
For external objects (such as those mapped to external tables, to OpenEdge Service objects, or through a D2C
connection), this function retrieves the ids of records related to a selected Rollbase record.
The current user must have View permission on the selected object type to run this API.
Note: For native Rollbase objects, you can use the method, rbf_getRelatedIds() on page 1051.
Syntax
rbf_getRelatedIds2(relName, objName, id, callback)
Parameters
relName
Integration name of selected Relationship definition
objName
The integration name of selected Object definition
id
ID of selected Object record
callback
A callback function that will receive parameters: relName, id, an array of related ids.
Note: This API is supported in portals as well.
Example
function my_callback(relName, objId, values) {
for (var i=0; i<values.length; i++) {
var amount = values[i];
// Do something...
}
}
rbf_getRelatedIds2("R12345", "obj1", id, my_callback);
1052 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Client-side AJAX API
rbf_runTrigger()
Warning: Support for using this method with external objects (such as those mapped to external tables,
to OpenEdge Service objects, or through a D2C connection) is a beta feature. This method is supported
in production systems, except for external objects.
Purpose
This function sends AJAX request to run a trigger on selected record.
The current user must have Edit permission on the selected object type to run this API.
Syntax
rbf_runTrigger(objName, id, triggerId, checkCondition, callback,
useLegacyDateFormat, options)
Parameters
objName
The integration name of the selected object definition
id
ID of the selected object record
triggerID
The integration name (string) or original ID (string) of trigger to run
checkCondition
If true, check trigger's condition formula before running trigger, otherwise ignore condition formula.
callback
A function to be called when AJAX request returns (optional). Will receive single parameter: true or
false depending on whether trigger has actually ran.
useLegacyDateFormat
This only applies to Date and Date/Time fields in JSON output. When set to false, a date value is
returned as a String. When set to true, a date value is returned as a Date object. Default value is
true
options
options is a list where maximum of two name-value pairs set in a variable in the form {name1 :
value1 , name2 : value2} can be configured. The possible names are runRecursions &
rollbackOnFailure with the values true or false.
• When the key runRecursions is set to true, it configures trigger to run recursively, assuming
recursive properties are set on the trigger definition page. Default value is false.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1053
Chapter 15: Reference
• When the key rollbackOnFailure is set to true, it configures trigger to revert the changes
which was the part of execution enabling the user to perform the action again. Default value is
false.
Note: This API is supported in portals as well.
Example
If you want the system to send email when portal user clicks on particular link on your portal page do the
following:
1. Prepare an email template.
2. Prepare a trigger to send email. This example uses the integration name sendEmail
3. Make sure the Edit operation is allowed for either Portal User or API User.
4. Prepare the following link:
<a href='#' onclick='rbf_runTrigger(
"myVisitor", {!#CURR_VISIT.id}, "sendEmail", false);'>Send Email</a>
For OpenEdge or any external objects use the {!#UID} token in quotes:
<a href='#' onclick='rbf_runTrigger("oeObject", {!#UID}, "sendEmail", false);'>Send
Email</a>
rbf_selectNumber()
Warning: Support for using this method with external objects (such as those mapped to external tables
or through a D2C connection) is a beta feature. This method is supported in production systems, except
for external objects.
Purpose
This function runs a SQL SELECT query on the server and returns a single decimal number to the callback
function. This is a simplified version of rbf_selectValue suitable for calculating totals etc.
The current user must have View permission on the selected object type to run this API.
The SELECT query used in this method consists of the following parts:
• The SELECT statement expects columns or expressions to be selected (mandatory). Use the field integration
names as SQL column names. You can use expressions such as COUNT(1). You cannot use * to retrieve
all columns.
• The FROM clause must consist of exactly one object name (mandatory).
• The WHERE clause can include a valid SQL expression to narrow the selection (optional). Use field integration
names as SQL column names.
• The ORDER BY clause can include a valid SQL expression to order the selection (optional). Use field
integration names as SQL column names.
You can use special tokens in your queries such as:
• TODAY for current time
• WEEK for 12PM of last Sunday
1054 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Client-side AJAX API
• MONTH for 12PM of 1st day of current month
• QUARTER for 12PM of 1st day of current quarter
• YEAR for 12PM of 1st day of current year
• CURR_USER for id of currently logged in user
Object and Field names are case-sensitive, while other components of the SQL query are not.
Use #code suffix to fetch integration codes for picklist fields rather than IDs. See Adding Logic to an Application
for more information.
Syntax
rbf_selectNumber(query, callback)
Parameters
query
SQL SELECT query.
callback
A callback function that will receive a single value returned by the query.
Note: This API is supported in portals as well.
rbf_selectQuery()
Warning: Support for using this method with external objects (such as those mapped to external tables
or through a D2C connection) is a beta feature. This method is supported in production systems, except
for external objects.
Purpose
This function runs a SQL SELECT query on the server and returns results as a 2D array to the callback function.
For fields that contain values for different languages, pass a langCode value in the options parameter to
get the values in a specific language. If the field does not allow multiple languages, or if there is no value for
the specified language, the value is returned in the tenant's base language. To use the options parameter,
you must specify a value for useLegacyDateFormat. Throws an error if the specified language code is not
configured for the tenant.
The current user must have View permission on the selected object type to run this API.
The SELECT query used in this method consists of the following parts:
• The SELECT statement expects columns or expressions to be selected (mandatory). Use the field integration
names as SQL column names. You can use expressions such as COUNT(1). You cannot use * to retrieve
all columns.
• The FROM clause must consist of exactly one object name (mandatory).
• The WHERE clause can include a valid SQL expression to narrow the selection (optional). Use field integration
names as SQL column names.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1055
Chapter 15: Reference
• The ORDER BY clause can include a valid SQL expression to order the selection (optional). Use field
integration names as SQL column names.
You can use special tokens in your queries such as:
• TODAY for current time
• WEEK for 12PM of last Sunday
• MONTH for 12PM of 1st day of current month
• QUARTER for 12PM of 1st day of current quarter
• YEAR for 12PM of 1st day of current year
• CURR_USER for id of currently logged in user
Object and Field names are case-sensitive, while other components of the SQL query are not.
Use #code suffix to fetch integration codes for picklist fields rather than IDs. See Adding Logic to an Application
for more information.
Syntax
rbf_selectQuery(query, maxRows, callback, useLegacyDateFormat, options);
Parameters
query
SQL SELECT query. See Query API section below for examples and limitations.
maxRows
Maximum number of rows to retrieve (1-20,000 range)
callback
A callback function that will receive a 2D JSON array with query results as parameter.
useLegacyDateFormat
This optional parameter only applies to JSON output and, specifically, to Date and Date/Time fields.
If true, or if not specified, a date value is returned as a Date object. If false, a date value is returned
as a String.
options
An optional JSON object that sets the values of optional arguments. The properties that this object
can take are as follows:
• langCode to a valid two-letter ISO language code, for example, {"langCode":"es"}
• useISODateFormat to get the date or date/time values in ISO format, for example,
{"useISODateFormat":true}.
• If the date and time value is Mon Jul 30 00:01:00 IST 2018 its equivalent ISO formatted
value 2018-07-29T18:31:00Z- is returned.
• If the date value is Mon Jul 30 2018, its equivalent ISO formatted value 2018-07-30 is
returned.
1056 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Client-side AJAX API
Note:
• This API is supported in portals as well.
• If both useLegacyDateFormat and useISODateFormat are set to true, useISODateFormat is applied.
Example
The following example returns the query result in French:
function my_callback(values) {
var amount = values[0][0];
var price = values[0][1];
// Do something...
}
rbf_selectQuery("select amount, price from order where id={!id}", 1, my_callback,
true,{"langCode":"fr"});
rbf_selectQuery2()
Warning: Support for using this method with external objects (such as those mapped to external tables
or through a D2C connection) is a beta feature. This method is supported in production systems, except
for external objects.
Purpose
This function runs a SQL SELECT query on the server and returns results as a 2D array to the callback function.
It differs from rbf_selectQuery() on page 1055 in that it takes a rowFrom parameter where you can specify a
starting row other than 0. For fields that contain values for different languages, pass a langCode value in the
options parameter to get the values in a specific language. If the field does not allow multiple languages, or
if there is no value for the specified language, the value is returned in the tenant's base language. To use the
options parameter, you must specify a value for useLegacyDateFormat. Throws an error if the specified
language code is not configured for the tenant.
The current user must have View permission on the selected object type to run this API.
The SELECT query used in this method consists of the following parts:
• The SELECT statement expects columns or expressions to be selected (mandatory). Use the field integration
names as SQL column names. You can use expressions such as COUNT(1). You cannot use * to retrieve
all columns.
• The FROM clause must consist of exactly one object name (mandatory).
• The WHERE clause can include a valid SQL expression to narrow the selection (optional). Use field integration
names as SQL column names.
• The ORDER BY clause can include a valid SQL expression to order the selection (optional). Use field
integration names as SQL column names.
You can use special tokens in your queries such as:
• TODAY for current time
• WEEK for 12PM of last Sunday
• MONTH for 12PM of 1st day of current month
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1057
Chapter 15: Reference
• QUARTER for 12PM of 1st day of current quarter
• YEAR for 12PM of 1st day of current year
• CURR_USER for id of currently logged in user
Object and Field names are case-sensitive, while other components of the SQL query are not.
Use #code suffix to fetch integration codes for picklist fields rather than IDs. See Adding Logic to an Application
for more information.
Syntax
rbf_selectQuery(query, rowFrom, maxRows, callback, useLegacyDateFormat, options);
Parameters
query
SQL SELECT query. See Query API section below for examples and limitations.
rowFrom
Number of row to start output (0 based)
maxRows
Maximum number of rows to retrieve (1-20,000 range)
callback
A callback function that will receive a 2D JSON array with query results as parameter.
useLegacyDateFormat
This optional parameter only applies to JSON output and, specifically, to Date and Date/Time fields.
If true, or if not specified, a date value is returned as a Date object. If false, a date value is returned
as a String.
options
An optional JSON object that sets the values of optional arguments. The properties that this object
can take are as follows:
• langCode to a valid two-letter ISO language code, for example, {"langCode":"es"}
• useISODateFormat to get the date or date/time values in ISO format, for example,
{"useISODateFormat":true}.
• If the date and time value is Mon Jul 30 00:01:00 IST 2018 its equivalent ISO formatted
value 2018-07-29T18:31:00Z- is returned.
• If the date value is Mon Jul 30 2018, its equivalent ISO formatted value 2018-07-30 is
returned.
Note:
• This API is supported in portals as well.
• If both useLegacyDateFormat and useISODateFormat are set to true, useISODateFormat is applied.
1058 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Client-side AJAX API
Example
The following example returns the query result in French:
function my_callback(values) {
var amount = values[0][0];
var price = values[0][1];
// Do something...
}
rbf_selectQuery2("select amount, price from order where id={!id}", 1, 10, my_callback,
true, {"langCode":"fr"});
rbf_selectValue()
Warning: Support for using this method with external objects (such as those mapped to external tables
or through a D2C connection) is a beta feature. This method is supported in production systems, except
for external objects.
Purpose
This function runs a SQL SELECT query on the server and returns a single value to the callback function. For
fields that contain values for different languages, pass a langCode value in the options parameter to get
the values in a specific language. If the field does not allow multiple languages, or if there is no value for the
specified language, the value is returned in the tenant's base language. To use the options parameter, you
must specify a value for useLegacyDateFormat. Throws an error if the specified language code is not
configured for the tenant.
The current user must have View permission on the selected object type to run this API.
The SELECT query used in this method consists of the following parts:
• The SELECT statement expects columns or expressions to be selected (mandatory). Use the field integration
names as SQL column names. You can use expressions such as COUNT(1). You cannot use * to retrieve
all columns.
• The FROM clause must consist of exactly one object name (mandatory).
• The WHERE clause can include a valid SQL expression to narrow the selection (optional). Use field integration
names as SQL column names.
• The ORDER BY clause can include a valid SQL expression to order the selection (optional). Use field
integration names as SQL column names.
You can use special tokens in your queries such as:
• TODAY for current time
• WEEK for 12PM of last Sunday
• MONTH for 12PM of 1st day of current month
• QUARTER for 12PM of 1st day of current quarter
• YEAR for 12PM of 1st day of current year
• CURR_USER for id of currently logged in user
Object and Field names are case-sensitive, while other components of the SQL query are not.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1059
Chapter 15: Reference
Use #code suffix to fetch integration codes for picklist fields rather than IDs. See Adding Logic to an Application
for more information.
Syntax
rbf_selectValue(query, callback, useLegacyDateFormat, options)
Parameters
query
SQL SELECT query.
callback
A callback function that will receive a single JSON value brought by the query.
useLegacyDateFormat
This optional parameter only applies to JSON output and, specifically, to Date and Date/Time fields.
If true, or if not specified, a date value is returned as a Date object. If false, a date value is returned
as a String.
options
An optional JSON object that sets the values of optional arguments. The properties that this object
can take are as follows:
• langCode to a valid two-letter ISO language code, for example, {"langCode":"es"}
• useISODateFormat to get the date or date/time values in ISO format, for example,
{"useISODateFormat":true}.
• If the date and time value is Mon Jul 30 00:01:00 IST 2018 its equivalent ISO formatted
value 2018-07-29T18:31:00Z- is returned.
• If the date value is Mon Jul 30 2018, its equivalent ISO formatted value 2018-07-30 is
returned.
Note:
• This API is supported in portals as well.
• If both useLegacyDateFormat and useISODateFormat are set to true, useISODateFormat is applied.
Example
The following example returns the query result in French:
function my_callback(returnAmt) {
// Do something...
}
rbf_selectValue("select amount from order where id={!id}", my_callback,
true,{"langCode":"fr"} );
1060 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Client-side AJAX API
rbf_setField()
Warning: Support for using this method with external objects (such as those mapped to external tables,
to OpenEdge Service objects, or through a D2C connection) is a beta feature. This method is supported
in production systems, except for external objects.
Purpose
This function sets the value of specified field for a selected RollbaseRollbase record and modifies the actual
record value without changing the UI presentation. Compare with rbf_setFieldValue() API which sets UI
presentation but does not immediately change backend value.
If an error occurred during update operation, an error notification procedure will be invoked .
For fields that allow values in multiple languages, use the fieldValue parameter to set values for additional
languages. If there is not already a value in a field for the tenant's base language, it is mandatory to supply a
value for the base language.
The current user must have Edit permission on the selected object type to run this API.
Syntax
rbf_setField(objName, id, fieldName, fieldValue, useIds, callback,
useLegacyDateFormat)
Parameters
objName
The integration name of the selected Object definition
id
ID of the selected object record
fieldName
The name of the field for which the value will be set
fieldValue
The new value for the field. For fields that support multiple languages, the value of this parameter
is a JSON object that specifies the two-letter ISO language code and value for each language, for
example:
{":en":"EnglishValue","el":"GreekValue"}
useIds
If true, the API will accept numeric IDs; if false (default) the API will return integration codes for status
fields and picklists
callback
A function to be executed when the operation is successful. It does not receive any parameters. This
is an optional parameter.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1061
Chapter 15: Reference
useLegacyDateFormat
This optional parameter only applies to JSON output and, specifically, to Date and Date/Time fields.
If true, or if not specified, a date value is returned as a Date object. If false, a date value is returned
as a String.
Note: This API is supported in portals as well.
rbf_updateRecord()
Warning: Support for using this method with external objects (such as those mapped to external tables,
to OpenEdge Service objects, or through a D2C connection) is a beta feature. This method is supported
in production systems, except for external objects.
Purpose
This method modifies record values of a RollbaseRollbase object without changing UI presentation. If an error
occurs during the operation, an error notification procedure will be invoked (see rbf_setErrorsCallback). For
fields that allow values in multiple languages, you can specify those values using the fieldMap parameter.
When updating field values, it only mandatory to update a field value in the tenant's base language when that
field does not already have a value in the base language.
The current user must have Edit permission on the selected object type to run this API.
Syntax
rbf_updateRecord(objName, id, fieldMap, useIds, callback, useLegacyDateFormat)
Parameters
objName
The integration name of the selected Object definition
id
ID of the selected Object record
fieldMap
A JSON object of the form: {"fieldIntegrationName1":value1,
"fieldIntegrationName2":value2}. When setting field values for multilingual fields, each
value can be a JSON object, for example:
{"fieldIntegrationName1":{"en":"EnglishValue1","ar":""ةشغشىن,"fr":"FrenchValue1"},
"fieldIntegrationName2":{"en":"EnglishValue2","ar":""ةشغشىن,"fr":"FrenchValue2"}}
useIds
If true, the API will accept numeric IDs; if false (default) the API will return integration codes for
status fields and picklists
1062 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Client-side AJAX API
callback
A function to be executed when the operation is successful. It does not receive any parameters. This
is an optional parameter.
useLegacyDateFormat
This optional parameter only applies to JSON output and, specifically, to Date and Date/Time fields.
If true, or if not specified, a date value is returned as a Date object. If false, a date value is returned
as a String.
Note: This API is supported in portals as well.
Field Manipulation
The functions in this section allow you to access and modify record fields.
Note: The field manipulation related APIs are supported in portals.
rbf_getFieldContent()
Warning: Support for using this method with external objects (such as those mapped to external tables,
to OpenEdge Service objects, or through a D2C connection) is a beta feature. This method is supported
in production systems, except for external objects.
Purpose
This function retrieves the HTML content of a read-only field on the current page.
Syntax
rbf_getFieldContent(fieldname)
Parameters
fieldName
The integration name of field
Note: This API is supported in portals as well.
rbf_getFieldValue()
Warning: Support for using this method with external objects (such as those mapped to external tables,
to OpenEdge Service objects, or through a D2C connection) is a beta feature. This method is supported
in production systems, except for external objects.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1063
Chapter 15: Reference
Purpose
This function retrieves the value of a field on current page with a given integration name. It will return null if the
field does not exist or is not included on the current page. For fields that contain values for different languages,
pass a langCode value in the options parameter to get the value in a specific language. To retrieve the
value in the tenant's base language, do not use the options parameter.
Syntax
rbf_getFieldValue(fieldName, options)
Parameters
fieldName
The field integration name.
options
An optional JSON object that sets the values of optional arguments. Currently this is only used for
setting langCode to a valid two-letter ISO language code, for example, {"langCode":"es"}.
Note: This API is supported in portals as well.
Example
The following example returns the Spanish value of the field with the integration name name.
rbf_getFieldValue("name",{"langCode":"es"});
rbf_getPicklistCode()
Warning: Support for using this method with external objects (such as those mapped to external tables,
to OpenEdge Service objects, or through a D2C connection) is a beta feature. This method is supported
in production systems, except for external objects.
Purpose
Returns the integration code of the currently selected option for a picklist, multi-select picklist, group of
checkboxes, or radio buttons field. This function works in View and Edit pages.
Syntax
rbf_getPicklistCode(fieldName)
Parameters
fieldName
The integration name of field
Note: This API is supported in portals as well.
1064 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Client-side AJAX API
rbf_getPicklistCodes()
Warning: Support for using this method with external objects (such as those mapped to external tables,
to OpenEdge Service objects, or through a D2C connection) is a beta feature. This method is supported
in production systems, except for external objects.
Purpose
This function returns a list of comma-separated integration codes corresponding to the currently selected
options in a picklist, multi-select picklist, or group of checkboxes field. This function works in view and edit
pages.
Syntax
rbf_getPicklistCodes(fieldName)
fieldName
The integration name of field
Note: This API is supported in portals as well.
rbf_setFieldContent()
Warning: Support for using this method with external objects (such as those mapped to external tables,
to OpenEdge Service objects, or through a D2C connection) is a beta feature. This method is supported
in production systems, except for external objects.
Purpose
This function sets the HTML content for a formula or template field on current page. It will have no effect if the
field does not exist on the current page.
Syntax
rbf_setFieldContent(fieldname, value)
Parameters
fieldName
The integration name of field
value
The new value to set
Note: This API is supported in portals as well.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1065
Chapter 15: Reference
rbf_setFieldValue()
Warning: Support for using this method with external objects (such as those mapped to external tables,
to OpenEdge Service objects, or through a D2C connection) is a beta feature. This method is supported
in production systems, except for external objects.
Purpose
This function sets the value of a field on current page with a given integration name. It will run the field's
onchange event handler if there is event handling code attached to that event. For fields that contain values
for different languages, pass a langCode value in the options parameter to set the value in a specific
language. To set the value in the tenant's base language, do not use the options parameter.
Syntax
rbf_setFieldValue(fieldname, value, options)
Parameters
fieldName
The integration name of field to set
value
Value to set
options
An optional JSON object that sets the values of optional arguments. Currently this is only used for
setting langCode to a valid two-letter ISO language code, for example, {"langCode":"es"}.
Note: This API is supported in portals as well.
Example
The following example sets the French value of the field with the integration name name:
rbf_setFieldValue("name", "Cafétéria", {"langCode":"fr"});
rbf_setFieldDisabled()
Warning: Support for using this method with external objects (such as those mapped to external tables,
to OpenEdge Service objects, or through a D2C connection) is a beta feature. This method is supported
in production systems, except for external objects.
1066 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Client-side AJAX API
Purpose
This function disables or enables an input field on the current page. It will have no effect if the field does not
exist on the current page. For fields that allow values in multiple languages, use the options parameter to
specify which language for which to disable/enable the input field. If the language code is invalid, or is not
included in the tenant's supported languages, the field will not be disabled or enabled.
Note: According to the HTML specification, disabled fields do not send data back to server when HTML form
is submitted. So if you wish disabled to send data (probably set by some client-side script) you can re-enable
input field in page's onSubmit event handler.
Syntax
rbf_setFieldDisabled(fieldname, isDisabled, options)
Parameters
fieldName
The integration name of field
isDisabled
The new value for "disabled" field's property
options
A JSON object containing langCode, whose value is an array of two-letter ISO language codes, for
example, {"langCode":["ar","he","fr"]}. The field will be disabled/enabled for those
languages.
Note: This API is supported in portals as well.
rbf_setPicklistCode()
Warning: Support for using this method with external objects (such as those mapped to external tables,
to OpenEdge Service objects, or through a D2C connection) is a beta feature. This method is supported
in production systems, except for external objects.
Purpose
This function can be executed on top of dependent picklist, mutli-picklist, and group of checkboxes. You can
provide a single value or an array of values for the optCode parameter.
Syntax
rbf_setPicklistCode(fieldName, optCode)
Parameters
fieldName
The integration name of field
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1067
Chapter 15: Reference
optCode
This value will be compared to the integration code of a particular picklist option
Note: This API is supported in portals as well.
Data Formatting
The methods in this section allow you to manipulate numbers, dates, and currency.
Note: The data formatting related APIs are supported in portals.
For extensive manipulation of Date and Time we have included moment.js (vanilla java script library), which
can be invoked in all Client-side APIs
rbf_getDate()
Warning: Support for using this method with external objects (such as those mapped to external tables,
to OpenEdge Service objects, or through a D2C connection) is a beta feature. This method is supported
in production systems, except for external objects.
Purpose
This function creates a JavaScript Date Object from a string. It returns null for an empty string.
Syntax
rbf_getDate(value)
Parameters
value
The string to convert to a Date Object
Note: This API is supported in portals as well.
rbf_getDigits()
Warning: Support for using this method with external objects (such as those mapped to external tables,
to OpenEdge Service objects, or through a D2C connection) is a beta feature. This method is supported
in production systems, except for external objects.
Purpose
Extracts digits from string value and ignores all other characters.
1068 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Client-side AJAX API
Syntax
rbf_getDigits(value)
Parameters
value
The string from which to extract digits
Note: This API is supported in portals as well.
rbf_getFloat()
Warning: Support for using this method with external objects (such as those mapped to external tables,
to OpenEdge Service objects, or through a D2C connection) is a beta feature. This method is supported
in production systems, except for external objects.
Purpose
Converts a given value from a string into a float number. It ignores symbols (e.g., $).
Syntax
rbf_getFloat(value)
Parameters
value
The string to convert
Note: This API is supported in portals as well.
rbf_formatCurrency()
Warning: Support for using this method with external objects (such as those mapped to external tables,
to OpenEdge Service objects, or through a D2C connection) is a beta feature. This method is supported
in production systems, except for external objects.
Purpose
Formats a given number into a currency string.
Syntax
rbf_formatCurrency(value, currSymbol, showZero, decPlaces, thsSep)
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1069
Chapter 15: Reference
Parameters
value
The number to format
currSymbol
currency symbol ($ by default)
showZero
If true, empty and NaN values are treated as "$0.00", otherwise as empty string ""
decPlaces
The number of decimal places (2 by default)
thsSep
The thousands separator (, by default)
Note: This API is supported in portals as well.
rbf_formatDate()
Warning: Support for using this method with external objects (such as those mapped to external tables,
to OpenEdge Service objects, or through a D2C connection) is a beta feature. This method is supported
in production systems, except for external objects.
Purpose
This function formats a JavaScript Date object into a string suitable for storing in Date input fields.
Note: When using the New UI, Progress recommends obtaining the date format from the user's localization
settings via the PageLocalization object. See the example below. See PageLocalization on page 1138 for more
information about the PageLocalization object. In addition, all date formats used in the New UI should conform
to those in the Kendo formatting library. See the Kendo UI documentation for more information.
Syntax
rbf_formatDate(d, format)
Parameters
d
A JavaScript Date object
format
The format to apply to the date, such as dd/mm/yyyy, mm.dd.yy, etc.
1070 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Client-side AJAX API
Note: This API is supported in portals as well.
Example
This example uses the PageLocalization object to populate the format parameter:
rbf_formatDate(new Date(), rbf_getPageContext().getPageLocalization().getDateFormat());
rbf_formatNumber()
Warning: Support for using this method with external objects (such as those mapped to external tables,
to OpenEdge Service objects, or through a D2C connection) is a beta feature. This method is supported
in production systems, except for external objects.
Purpose
Formats a given number into a decimal string.
Syntax
rbf_formatNumber(value, decPlaces, decSeparator, thsSep)
Parameters
value
The number to format
decPlaces
The number of decimal places (2 by default)
decSeparator
The symbol used to separate the integer part from the fractional part of a decimal number. ("." by
default)
thsSep
The thousands separator (none by default).
Note: This API is supported in portals as well.
Example
var x = rbf_formatNumber(7000123.45,4,'.',',');
Result: 7,000,123.4500
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1071
Chapter 15: Reference
rbf_formatUsingMask()
Warning: Support for using this method with external objects (such as those mapped to external tables,
to OpenEdge Service objects, or through a D2C connection) is a beta feature. This method is supported
in production systems, except for external objects.
Purpose
Formats a string containing digits as specified in the mask parameter.
Syntax
rbf_formatUsingMask(value, mask)
Parameters
value
The string to format
mask
The input mask, which uses # as a placeholder for a digit
Note: This API is supported in portals as well.
Example
var x = rbf_formatUsingMask("123456789", "###-##-####");
Result: 123-45-6789
rbf_getInt()
Warning: Support for using this method with external objects (such as those mapped to external tables,
to OpenEdge Service objects, or through a D2C connection) is a beta feature. This method is supported
in production systems, except for external objects.
Purpose
This function converts a given value from a string into an integer number. It ignores symbols (e.g., $).
Syntax
rbf_getInt(value)
Parameters
value
The string to convert
1072 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Client-side AJAX API
Note: This API is supported in portals as well.
Grid Control Examples and API
Grid controls allow users creating or editing a record to add, delete, and edit all records for a particular
relationship. For example, the screen below shows a grid control that displays the order lines associated with
a particular order:
The JavaScript API functions described in this section can be used to manipulate the rows and cells of an
existing Grid Control. At least one grid control must exist on a page before you can configure grids or use the
grid APIs. See Using grid controls to manage multiple records on page 383 for information on adding, configuring
and using grid controls. All Grid API names have the suffix 2 to distinguish them from the deprecated API.
Field-level HTML event handlers do not apply to fields in a grid control since there may be any number of
instances of the same field in a grid. Therefore, Rollbase provides special grid event handling options. Grid
Controls provide three types of event handlers:
• onCreate — invoked when a new row is added
• onUpdate — invoked when one of the controls in the current row is modified
• onDelete — invoked when a row is deleted
These handlers work similarly to event handlers attached to individual HTML input fields. However, the symbol
@@ in grid event handlers will be replaced by the current row number and the symbol, ##, will be replaced by
the gridNo parameter used by Rollbase Client-side API.
Rollbase allows multiple grid controls on page. Therefore to distinguish between the grids on a page, all
grid-related methods take the 0-based sequential number of the grid as first parameter. To find the grid number,
navigate to the page containing the grid, click Configure Grid, and navigate to the last page of the wizard, as
shown below:
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1073
Chapter 15: Reference
Note: The grid control related APIs are not supported in portals.
Simple Grid Calculation Example
You can add JavaScript that dynamically updates totals as a user adds or modifies grid records. This example
uses a Purchase Order object that has a 1-to-many relationship with a Line Item object. The Line Item object
has three fields:
1. An integer field with the integration name: quantity
2. A currency field with the integration name: price
3. A formula field with the integration name: total, a formula body: {!quantity}*{!price}, and a return
type of currency.
The New Purchase Order page with a grid added will look like the following screen. Users adding line items
must save the parent record before they can view the total quantity and price.
1074 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Client-side AJAX API
By adding an event handler, a script component, and JavaScript to perform the calculations, the grid totals will
dynamically update when the user tabs out of the calculated fields, as shown below:
To recreate this example, follow these steps:
1. Use the Page Editor to add a Grid Control to the Edit and New pages for Purchase Order objects. See
Adding a grid control to a page on page 384 for detailed procedures.
2. Configure the grids as follows:
a. Create a Purchase Order record. On the New page, click Configure Grid.
b. Select the relationship Purchase Order-Line Item.
c. Select these fields to be displayed in the grid: Quantity, Price, and Total.
d. For Grid Totals, select the Quantity and Total columns and select the Total operation for both.
e. In the JavaScript Event Handlers section onUpdate field, add the following call (the @@ symbol will be
replaced at runtime with the current row number):
rbf_showGridRow(@@)
f. Click Save & Synchronize.
g. Select the Edit page.
h. Click Save and the changes will be applied to both pages.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1075
Chapter 15: Reference
3. Add the JavaScript for calculating totals:
a. Click Design This Page.
b. From the Create section of the left pane, drag a New Section component onto the page below the Grid
Control.
c. Select the new section and from the Properties section in the left pane remove the Section Title. Since
the JavaScript will not display on the page, you don't want the title to show either.
d. Drag a new Script Component from the left pane and drop it in the New Section.
e. Click Edit.
f. In the editor, add the following JavaScript:
<script>
function rbf_showGridRow(rowIndex) {
var a = rbf_getFloat(rbf_getGridValue2(0, 'quantity', rowIndex));
var p = rbf_getFloat(rbf_getGridValue2(0, 'price', rowIndex));
var t = a*p; rbf_setGridContent2(0, 'total', rowIndex, rbf_formatCurrency(t));
}
</script>
g. Click Save & Synchronize.
h. Select the Edit page.
i. Click Save and the changes will be applied to both pages.
4. Test by creating a new record and adding line items. Note that when you tab out of the quantity and price
fields, the totals update automatically.
Advanced Grid Example
Consider a more complex use case than that shown in Simple Grid Calculation Example on page 1074. Suppose
that you want the user to select an item price from a price list instead of inputting it directly. To the data model
described in Simple Grid Calculation Example on page 1074 you could add a relationship (R8011504) with a
Catalog Item object.
The JavaScript to handle this use case would be as follows:
<script>
var m_rowIndex = -1;
function rbf_findPrice(rowIndex) {
m_rowIndex = -1;
var catId = rbf_getInt(rbf_getGridValue2(0, 'R8011504', rowIndex));
var p = rbf_getFloat(rbf_getGridValue2(0, 'price', rowIndex));
if (catId>0 && p<=0) {
rbf_getFields("catalog_item", catId, "msrp", rbf_callback);
m_rowIndex = rowIndex;
}
else {
rbf_showGridRow(rowIndex);
}
}
function rbf_showGridRow(rowIndex) {
var a = rbf_getFloat(rbf_getGridValue2(0, 'quantity', rowIndex));
var p = rbf_getFloat(rbf_getGridValue2(0, 'price', rowIndex));
var t = a*p;
rbf_setGridContent2(0, 'total', rowIndex, rbf_formatCurrency(t));
}
1076 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Client-side AJAX API
function rbf_callback(objName, objId, values) {
var p = values["msrp"];
if (m_rowIndex >= 0) {
rbf_setGridValue2('price', m_rowIndex, p);
rbf_showGridRow(m_rowIndex);
}
}
</script>
Set rbf_findPrice(@@) as an onUpdate event handler in the Grid.
The functions perform the following:
• If a related Catalog Item is selected but the Price field is not set yet, the rbf_findPrice() function sends
an AJAX request using rbf_getFields() to determine the price of the selected item and return it.
Otherwise rbf_showGridRow() calculates the Line Item totals.
• The rbf_callback function processes the information fetched by the AJAX response. It finds the 'msrp'
value from response and copies it to the 'price' field, and then updates the grid row using
rbf_showGridRow().
rbf_addGridRow()
Warning: Support for using this method with external objects (such as those mapped to external tables,
to OpenEdge Service objects, or through a D2C connection) is a beta feature. This method is supported
in production systems, except for external objects.
Purpose
Adds a new empty row to a grid.
Syntax
rbf_addGridRow(gridNo)
Parameters
gridNo
The 0-based number of Grid Control on page
Note: This API is not supported in portals.
rbf_delGridRow()
Warning: Support for using this method with external objects (such as those mapped to external tables,
to OpenEdge Service objects, or through a D2C connection) is a beta feature. This method is supported
in production systems, except for external objects.
Purpose
Deletes the row with given index from a grid.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1077
Chapter 15: Reference
Syntax
rbf_delGridRow(gridNo, rowIndex)
Parameters
gridNo
The 0-based number of the grid control on the page
rowIndex
The row number. Row numbers start with 0.
Note: This API is not supported in portals.
rbf_getGridControlComponent()
Purpose
Returns the GridControl on page 1133 object from the current page in the position specified by the gridNo
parameter. You can also get a GridControl object using rbf_getPageComponent() on page 1115.
Note: This API and the GridControl on page 1133 object are only available in the New UI.
Syntax
rbf_getGridControlComponent(gridNo)
Parameters
gridNo
The order in which the grid control appears on the page. For the first grid control on the page, the
value is 0, for the second grid control on the page, the value is 1, and so on.
Note: This API is not supported in portals.
Return value
The specified GridControl on page 1133 object.
Example
The following example returns the number of grid rows in the first grid control component on the current page:
var numberOfGridRows = rbf_getGridControlComponent(0).getMaxRowIndex();
1078 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Client-side AJAX API
rbf_getGridFieldContext()
Purpose
Returns the GridFieldContext on page 1134 object for the specified grid control, row index, and field.
Note: This API and the GridFieldContext object are only available in the New UI.
Syntax
rbf_getGridFieldContext(gridNo, rowIndex, fieldName)
Parameters
gridNo
The order in which the grid control appears on the page. For the first grid control on the page, the
value is 0, for the second grid control on the page, the value is 1, and so on.
rowIndex
The index of the row of the grid from which to return the field context.
fieldName
The field integration name.
Note: This API is not supported in portals.
Return value
The specified .
Example
The following example returns a JSON object representing the value of the description field in the fourth row
of the second grid control component on the current page:
var fieldData = rbf_getGridFieldContext(1, 3, "description").getGridFieldData();
rbf_getGridField()
Warning: Support for using this method with external objects (such as those mapped to external tables,
to OpenEdge Service objects, or through a D2C connection) is a beta feature. This method is supported
in production systems, except for external objects.
Purpose
Gets the name of the field that was last changed in the Grid.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1079
Chapter 15: Reference
Syntax
rbf_getGridField(gridNo)
Parameters
Parameter
Description
gridNo
The 0-based number of Grid Control on page
Note: This API is not supported in portals.
rbf_getGridPicklistCode()
Warning: Support for using this method with external objects (such as those mapped to external tables,
to OpenEdge Service objects, or through a D2C connection) is a beta feature. This method is supported
in production systems, except for external objects.
Purpose
Gets the integration code of a grid control picklist field with the given integration name at the specified row
number. Returns null if the grid control does not exist on the current page.
Syntax
rbf_getGridPicklistCode(gridNo, fieldName, rowIndex);
Parameters
gridNo
The 0-based number of the grid control on the page
fieldName
The integration name of the input field
rowIndex
The row number. Row numbers start with 0.
Note: This API is not supported in portals.
Return Value
The integration code of the grid control picklist field. Null if the grid control does not exist on the page.
1080 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Client-side AJAX API
rbf_getGridValue2()
Warning: Support for using this method with external objects (such as those mapped to external tables,
to OpenEdge Service objects, or through a D2C connection) is a beta feature. This method is supported
in production systems, except for external objects.
Purpose
Gets the value of a single field in a grid control with the given integration name at the specified row number.
Returns null if a field or grid control does not exist on the current page.
Syntax
rbf_getGridValue2(gridNo, fieldName, rowIndex)
Parameters
gridNo
The 0-based number of the grid control on the page
fieldName
The integration name of the input field
rowIndex
The row number. Row numbers start with 0.
Note: This API is not supported in portals.
rbf_getMaxRowIndex2()
Warning: Support for using this method with external objects (such as those mapped to external tables,
to OpenEdge Service objects, or through a D2C connection) is a beta feature. This method is supported
in production systems, except for external objects.
Purpose
Returns the maximum value for the rowIndex in a grid. This may be different from the total number of rows in
the grid.
Note: A rowIndex is assigned to each grid row when it is first created or rendered. Deleting a row does not
affect (decrement) indexes of other rows.
Syntax
rbf_getMaxRowIndex2(gridNo)
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1081
Chapter 15: Reference
Parameters
gridNo
The 0-based number of Grid Control on page
Note: This API is not supported in portals.
Example
This function can be used to iterate through all grid rows:
var n = rbf_getMaxRowIndex2(0);
for (var rowIndex=0; rowIndex<n; rowIndex++) {
var x = rbf_getGridValue2(0, "amount", rowIndex);
}
rbf_setGridContent2()
Warning: Support for using this method with external objects (such as those mapped to external tables,
to OpenEdge Service objects, or through a D2C connection) is a beta feature. This method is supported
in production systems, except for external objects.
Purpose
Sets the HTML content for a formula or template field in GridControl. Has no effect if the fields don't exist in
GridControl.
Syntax
rbf_setGridContent2(gridNo, fieldName, rowIndex, value)
Parameters
gridNo
The 0-based number of the grid control on the page
fieldName
The integration name of formula or template field
rowIndex
The row number. Row numbers start with 0.
value
The HTML content to be assigned to the cell
Note: This API is not supported in portals.
1082 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Client-side AJAX API
rbf_setGridPicklistCode()
Warning: Support for using this method with external objects (such as those mapped to external tables,
to OpenEdge Service objects, or through a D2C connection) is a beta feature. This method is supported
in production systems, except for external objects.
Purpose
Sets integration code of picklist field in a grid control with the given integration name at the specified row
number. Has no effect if a field or grid control does not exist on the current page. This function is similar to
rbf_setPicklistCode() on page 1067.
Syntax
rbf_setGridPicklistCode(gridNo, fieldName, rowIndex, optCode)
Parameters
gridNo
The 0-based number of the grid control on the page
fieldName
The integration name of the input field
rowIndex
The row number. Row numbers start with 0.
optCode
Value will be compared to the integration code of a particular picklist option
Note: This API is not supported in portals.
rbf_setGridValue2()
Warning: Support for using this method with external objects (such as those mapped to external tables,
to OpenEdge Service objects, or through a D2C connection) is a beta feature. This method is supported
in production systems, except for external objects.
Purpose
Sets the value of a single editable field in the grid control with the given integration name at the specified row
number. Has no effect if a field or grid control does not exist on the current page.
Syntax
rbf_setGridValue2(gridNo, fieldName, rowIndex, value)
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1083
Chapter 15: Reference
Parameters
gridNo
The 0-based number of the grid control on the page
fieldName
The integration name of the input field
rowIndex
The row number. Row number start with 0.
value
HTML content to set in field
Note: This API is not supported in portals.
rbf_showGridTotals()
Warning: Support for using this method with external objects (such as those mapped to external tables,
to OpenEdge Service objects, or through a D2C connection) is a beta feature. This method is supported
in production systems, except for external objects.
Purpose
Calculate and display totals for grid.
Syntax
rbf_showGridTotals(gridNo)
Parameters
gridNo
The 0-based number of Grid Control on page
Note: This API is not supported in portals.
rbf_sumGridColumn2()
Warning: Support for using this method with external objects (such as those mapped to external tables,
to OpenEdge Service objects, or through a D2C connection) is a beta feature. This method is supported
in production systems, except for external objects.
1084 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Client-side AJAX API
Purpose
Retrieves the sum of column values in a grid.
Syntax
rbf_sumGridColumn2(gridNo, fieldName)
Parameters
gridNo
The 0-based number of Grid Control on page
fieldName
The integration name of formula or numeric input field
Note: This API is not supported in portals.
AJAX Metadata API
The server-side AJAX APIs provides methods to retrieve, create, update, and delete the following Rollbase
metadata elements:
• Application
• Object
• Field
• Relationship
Note: All metadata methods require administrative privileges, regardless of the view, edit, create and delete
permissions set on the application or object. Establish the session to use these methods by logging in with
credentials for an administrative user.
To use the metadata API you must reference metadata.js on your web page. Use the Page Editor and add
the following HTML code-snippet to your Script component:
<script src='../js/metadata.js' type='text/javascript' charset='utf-8'></script>
Note: This code-snippet is available through the Helper user interface.
For more information about XML metadata definitions for Rollbase applications, see Metadata XML reference
on page 1158.
Note: The metadata related APIs are supported in portals.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1085
Chapter 15: Reference
rbf_createApplicationDef()
Warning: Support for using this method with external objects (such as those mapped to external tables,
to OpenEdge Service objects, or through a D2C connection) is a beta feature. This method is supported
in production systems, except for external objects.
Purpose
Creates an application from an XML document.
Syntax
rbf_createApplicationDef(xmlString, callback, errorCallback)
Parameters
xmlString
A string containing the XML document describing the application to be created.
callback
A function to process the specified operation and receive its result, in the XML format, as the first
argument.
errorCallback
An optional parameter to receive an error message as the first argument. If you do not specify this
parameter in the method call, the callback defined by rbf_setErrorsCallback(callback) is
invoked to receive the error message.
Note: This API is supported in portals as well.
For information about the XML elements in an Application, see Application XML Elements on page 1158.
rbf_createFieldDef()
Warning: Support for using this method with external objects (such as those mapped to external tables,
to OpenEdge Service objects, or through a D2C connection) is a beta feature. This method is supported
in production systems, except for external objects.
Purpose
Creates a field definition from an XML document.
Syntax
rbf_createFieldDef(xmlString, callback, errorCallback)
1086 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Client-side AJAX API
Parameters
xmlString
A string containing the XML document describing the field to be created.
callback
A function to process the specified operation and receive its result, in the XML format, as the first
argument.
errorCallback
An optional parameter to receive an error message as the first argument. If you do not specify this
parameter in the method call, the callback defined by rbf_setErrorsCallback(callback) is
invoked to receive the error message.
Note: This API is supported in portals as well.
For information about the XML definitions in a field, see Field XML Definition on page 1166.
rbf_createObjectDef()
Warning: Support for using this method with external objects (such as those mapped to external tables,
to OpenEdge Service objects, or through a D2C connection) is a beta feature. This method is supported
in production systems, except for external objects.
Purpose
Creates a new object definition, including any specified fields and relationships, from an XML document.
Syntax
rbf_createObjectDef(xmlString, callback, errorCallback)
Parameters
xmlString
A string containing the XML document describing the object to be created.
callback
A function to process the specified operation and receive its result, in the XML format, as the first
argument.
errorCallback
An optional parameter to receive an error message as the first argument. If you do not specify this
parameter in the method call, the callback defined by rbf_setErrorsCallback(callback) is
invoked to receive the error message.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1087
Chapter 15: Reference
Note: This API is supported in portals as well.
For information about the XML definitions in an object, see Object XML Definition on page 1161.
rbf_createRelationshipDef()
Warning: Support for using this method with external objects (such as those mapped to external tables,
to OpenEdge Service objects, or through a D2C connection) is a beta feature. This method is supported
in production systems, except for external objects.
Purpose
Creates a new relationship from an XML document.
Syntax
rbf_createRelationshipDef(xmlString, callback, errorCallback)
Parameters
xmlString
A string containing the XML document describing the relationship to be created.
callback
A function to process the specified operation and receive its result, in the XML format, as the first
argument.
errorCallback
An optional parameter to receive an error message as the first argument. If you do not specify this
parameter in the method call, the callback defined by rbf_setErrorsCallback(callback) is
invoked to receive the error message.
Note: This API is supported in portals as well.
For information about the XML definitions in a relationship, see Relationship XML Definition on page 1172.
rbf_deleteApplicationDef()
Warning: Support for using this method with external objects (such as those mapped to external tables,
to OpenEdge Service objects, or through a D2C connection) is a beta feature. This method is supported
in production systems, except for external objects.
Purpose
Deletes an application definition and all of its component definitions.
1088 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Client-side AJAX API
Syntax
rbf_deleteApplicationDef(appId, callback, errorCallback)
Parameters
appId
The original application ID.
callback
A function to process the specified operation and receive its result, in the XML format, as the first
argument.
errorCallback
An optional parameter to receive an error message as the first argument. If you do not specify this
parameter in the method call, the callback defined by rbf_setErrorsCallback(callback) is
invoked to receive the error message.
Note: This API is supported in portals as well.
For information about the XML elements in an Application, see Application XML Elements on page 1158.
rbf_deleteFieldDef()
Warning: Support for using this method with external objects (such as those mapped to external tables,
to OpenEdge Service objects, or through a D2C connection) is a beta feature. This method is supported
in production systems, except for external objects.
Purpose
Deletes a field definition from the specified object.
Syntax
rbf_deleteFieldDef(objName, fieldName, callback, errorCallback)
Parameters
objName
The object Integration name.
fieldName
The field integration name.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1089
Chapter 15: Reference
callback
A function to process the specified operation and receive its result, in the XML format, as the first
argument.
errorCallback
An optional parameter to receive an error message as the first argument. If you do not specify this
parameter in the method call, the callback defined by rbf_setErrorsCallback(callback) is
invoked to receive the error message.
Note: This API is supported in portals as well.
For information about the XML definitions in a field, see Field XML Definition on page 1166.
rbf_deleteObjectDef()
Warning: Support for using this method with external objects (such as those mapped to external tables,
to OpenEdge Service objects, or through a D2C connection) is a beta feature. This method is supported
in production systems, except for external objects.
Purpose
Deletes an object definition, including its fields and relationships.
Syntax
rbf_deleteObjectDef(objName, callback, errorCallback)
Parameters
objName
The object Integration name.
callback
A function to process the specified operation and receive its result, in the XML format, as the first
argument.
errorCallback
An optional parameter to receive an error message as the first argument. If you do not specify this
parameter in the method call, the callback defined by rbf_setErrorsCallback(callback) is
invoked to receive the error message.
Note: This API is supported in portals as well.
For information about the XML definitions in an object, see Object XML Definition on page 1161.
1090 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Client-side AJAX API
rbf_deleteRelationshipDef()
Warning: Support for using this method with external objects (such as those mapped to external tables,
to OpenEdge Service objects, or through a D2C connection) is a beta feature. This method is supported
in production systems, except for external objects.
Purpose
Deletes a relationship definition.
Syntax
rbf_deleteRelationshipDef(relName, callback, errorCallback)
Parameters
relName
The relationship integration name.
callback
A function to process the specified operation and receive its result, in the XML format, as the first
argument.
errorCallback
An optional parameter to receive an error message as the first argument. If you do not specify this
parameter in the method call, the callback defined by rbf_setErrorsCallback(callback) is
invoked to receive the error message.
Note: This API is supported in portals as well.
For information about the XML definitions in a relationship, see Relationship XML Definition on page 1172.
rbf_getApplicationDef()
Warning: Support for using this method with external objects (such as those mapped to external tables,
to OpenEdge Service objects, or through a D2C connection) is a beta feature. This method is supported
in production systems, except for external objects.
Purpose
Retrieves an XML description of a Rollbase application.
Syntax
rbf_getApplicationDef(appId,callback,errorCallback)
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1091
Chapter 15: Reference
Parameters
appId
The original application ID.
callback
A function to process the specified operation and receive its result, in the XML format, as the first
argument.
errorCallback
An optional parameter to receive an error message as the first argument. If you do not specify this
parameter in the method call, the callback defined by rbf_setErrorsCallback(callback) is
invoked to receive the error message.
Note: This API is supported in portals as well.
For information about the XML elements in an application, see Application XML Elements on page 1158.
rbf_getFieldDef()
Warning: Support for using this method with external objects (such as those mapped to external tables,
to OpenEdge Service objects, or through a D2C connection) is a beta feature. This method is supported
in production systems, except for external objects.
Purpose
Retrieves a field definition as an XML document.
Syntax
rbf_getFieldDef(objname, fieldName, callback, errorCallback)
Parameters
objName
The object Integration name.
fieldName
The field integration name.
callback
A function to process the specified operation and receive its result, in the XML format, as the first
argument.
1092 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Client-side AJAX API
errorCallback
An optional parameter to receive an error message as the first argument. If you do not specify this
parameter in the method call, the callback defined by rbf_setErrorsCallback(callback) is
invoked to receive the error message.
Note: This API is supported in portals as well.
For information about the XML definitions in a field, see Field XML Definition on page 1166.
rbf_getObjectDef()
Warning: Support for using this method with external objects (such as those mapped to external tables,
to OpenEdge Service objects, or through a D2C connection) is a beta feature. This method is supported
in production systems, except for external objects.
Purpose
Retrieves the specified object definition and returns it as an XML document.
Syntax
rbf_getObjectDef(objName, callback, errorCallback)
Parameters
objName
The object Integration name.
callback
A function to process the specified operation and receive its result, in the XML format, as the first
argument.
errorCallback
An optional parameter to receive an error message as the first argument. If you do not specify this
parameter in the method call, the callback defined by rbf_setErrorsCallback(callback) is
invoked to receive the error message.
Note: This API is supported in portals as well.
For information about the XML definitions in an object, see Object XML Definition on page 1161.
rbf_getRelationshipDef()
Warning: Support for using this method with external objects (such as those mapped to external tables,
to OpenEdge Service objects, or through a D2C connection) is a beta feature. This method is supported
in production systems, except for external objects.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1093
Chapter 15: Reference
Purpose
Retrieves a relationship definition as an XML document.
Syntax
rbf_getRelationshipDef(relName, callback, errorCallback)
Parameters
relName
The relationship integration name.
callback
A function to process the specified operation and receive its result, in the XML format, as the first
argument.
errorCallback
An optional parameter to receive an error message as the first argument. If you do not specify this
parameter in the method call, the callback defined by rbf_setErrorsCallback(callback) is
invoked to receive the error message.
Note: This API is supported in portals as well.
For information about the XML definitions in a relationship, see Relationship XML Definition on page 1172.
rbf_updateApplicationDef()
Warning: Support for using this method with external objects (such as those mapped to external tables,
to OpenEdge Service objects, or through a D2C connection) is a beta feature. This method is supported
in production systems, except for external objects.
Purpose
Updates an application from an XML document.
Syntax
rbf_updateApplicationDef(xmlString, callback, errorCallback)
Parameters
xmlString
A string containing the XML document describing the application to be updated.
1094 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Client-side AJAX API
callback
A function to process the specified operation and receive its result, in the XML format, as the first
argument.
errorCallback
An optional parameter to receive an error message as the first argument. If you do not specify this
parameter in the method call, the callback defined by rbf_setErrorsCallback(callback) is
invoked to receive the error message.
Note: This API is supported in portals as well.
For information about the XML elements in an Application, see Application XML Elements on page 1158.
rbf_updateFieldDef()
Warning: Support for using this method with external objects (such as those mapped to external tables,
to OpenEdge Service objects, or through a D2C connection) is a beta feature. This method is supported
in production systems, except for external objects.
Purpose
Updates a field definition from an XML document.
Syntax
rbf_updateFieldDef(xmlString, callback, errorCallback)
Parameters
xmlString
A string containing the XML document describing the field to be updated.
callback
A function to process the specified operation and receive its result, in the XML format, as the first
argument.
errorCallback
An optional parameter to receive an error message as the first argument. If you do not specify this
parameter in the method call, the callback defined by rbf_setErrorsCallback(callback) is
invoked to receive the error message.
Note: This API is supported in portals as well.
For information about the XML definitions in a field, see Field XML Definition on page 1166.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1095
Chapter 15: Reference
rbf_updateObjectDef()
Warning: Support for using this method with external objects (such as those mapped to external tables,
to OpenEdge Service objects, or through a D2C connection) is a beta feature. This method is supported
in production systems, except for external objects.
Purpose
Updates an object definition from an XML document.
Syntax
rbf_updateObjectDef(xmlString, callback, errorCallback)
Parameters
xmlString
A string containing the XML document describing the object to be updated.
callback
A function to process the specified operation and receive its result, in the XML format, as the first
argument.
errorCallback
An optional parameter to receive an error message as the first argument. If you do not specify this
parameter in the method call, the callback defined by rbf_setErrorsCallback(callback) is
invoked to receive the error message.
Note: This API is supported in portals as well.
For information about the XML definitions in an object, see Object XML Definition on page 1161.
rbf_updateRelationshipDef()
Warning: Support for using this method with external objects (such as those mapped to external tables,
to OpenEdge Service objects, or through a D2C connection) is a beta feature. This method is supported
in production systems, except for external objects.
Purpose
Updates a relationship definition from an XML document.
Syntax
rbf_updateRelationshipDef(xmlString, callback, errorCallback)
1096 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Client-side AJAX API
Parameters
xmlString
A string containing the XML document describing the relationship to be updated.
callback
A function to process the specified operation and receive its result, in the XML format, as the first
argument.
errorCallback
An optional parameter to receive an error message as the first argument. If you do not specify this
parameter in the method call, the callback defined by rbf_setErrorsCallback(callback) is
invoked to receive the error message.
Note: This API is supported in portals as well.
For information about the XML definitions in a relationship, see Relationship XML Definition on page 1172.
Miscellaneous
Methods in this section allow you to obtain information such as integration codes and IDs, determine or set the
state of checkboxes, and set a callback for error conditions.
Note: The APIs in this section are supported in portals.
rbf_addOnLoadMethod()
Purpose
Attaches an onload event handler function to a page. This function is useful as a shorthand for adding an
onload event handler function to a page. Call this function in a script or HTML component on the page for
which you want to add an onload event handler. This function works for both the New UI and the Classic UI.
For the New UI, it works for both page refresh using AJAX as well as for a complete page load.
See HTML event handlers on page 513 and Managing object pages on page 364 for more information about
onload functions.
Note: Progress strictly discourages using the document.ready jQuery function.
Syntax
rbf_addOnLoadMethod(callback)
Parameters
callback
The name of the function to use as a onload event handler.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1097
Chapter 15: Reference
Note: This API is supported in portals as well.
Example
The following example prints a message to the console when the page loads.
<script>
var onLoad = function () {
if(console){
console.log("Executing function on page load");
}
};
rbf_addOnLoadMethod(onLoad);
</script>
rbf_getCodeById()
Warning: Support for using this method with external objects (such as those mapped to external tables,
to OpenEdge Service objects, or through a D2C connection) is a beta feature. This method is supported
in production systems, except for external objects.
Purpose
Returns the code of an item from a picklist, status, radio buttons, or group of checkboxes field for the specified
ID.
Syntax
rbf_getCodeById(objName, fieldName, id, callback)
Parameters
objName
The object definition integration name
fieldName
The integration name of field
id
ID of field item
callback
The callback function that will receive code of field item as first parameter (null if not found).
Note: This API is supported in portals as well.
1098 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Client-side AJAX API
rbf_getExchangeRate()
Warning: Support for using this method with external objects (such as those mapped to external tables,
to OpenEdge Service objects, or through a D2C connection) is a beta feature. This method is supported
in production systems, except for external objects.
Purpose
Returns an exchange rate between two currencies on a given date.
Syntax
rbf_getExchangeRate(srcCode, destCode, date, callback)
Parameters
srcCode
The currency code to convert from
destCode
The currency code to convert to
date
The date for exchange rate (current date by default)
callback
The callback function that will receive exchange rate as first parameter (null if not found)
Note: This API is supported in portals as well.
Example
rbf_getExchangeRate("EUR", "USD", null, function(rate) { alert("EUR/USD="+rate); });
rbf_getIdByCode()
Warning: Support for using this method with external objects (such as those mapped to external tables,
to OpenEdge Service objects, or through a D2C connection) is a beta feature. This method is supported
in production systems, except for external objects.
Purpose
Returns the ID of an item from a picklist, status, radio buttons, or group of checkboxes field for the specified
code.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1099
Chapter 15: Reference
Syntax
rbf_getIdByCode(objName, fieldName, code, callback)
Parameters
objName
Object definition integration name
fieldName
The integration name of field
code
The integration name of the field item
callback
The callback function that will receive the ID of field item as first parameter (-1 if not found).
Note: This API is supported in portals as well.
rbf_getIdByOriginalId()
Purpose
Given the original ID and an entity type, passes the entity's ID to the specified callback function. If an entity
of the specified type with the specified original ID does not exist, sets the HTTP status to 500 and executes
the error callback function configured using rbf_setErrorsCallback().
Note: If this function call results in an error, and you have not configured an error callback function using
rbf_setErrorsCallback(), you will still see the HTTP status of 500 but will not see the reason for the
error.
Syntax
rbf_getIdByOriginalId(entityType, originalId, callback);
Parameters
entityType
A string indicating the type of entity. Can be one of "object", "field", "relationship",
"webpage", "view", "template", "report", "chart", "gauge", "trigger", "process",
"status", "action", "button", or "datamap".
origId
The original ID of the entity.
1100 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Client-side AJAX API
callback
The callback function that will receive the ID of the entity as its first parameter.
Return value
If successful, passes the entity's ID to callback function and sets the HTTP status to 200. If unsuccessful,
sets the HTTP status to 500 and passes the error message to the configured error callback function (see
above).
Note: This API is supported in portals as well.
Example
The following example retrieves the ID of the specified object definition and outputs it to the console. If there
is an error, the error callback function displays an alert with an error message:
<script>
var callback = function(errMsg, apiName) {
alert("ERROR: "+errMsg+" in: "+apiName);
}
rbf_setErrorsCallback(callback);
var handleResponse = function (id) {
if(console){
console.log("**** Processing handleResponse ****");
console.log("ID is: ", id);
}
}
rbf_getIdByOriginalId("object", "7550", handleResponse);
</script>
With successful execution, the object definition's ID is printed to the console:
ID is: 150049675
In the above example, If there is no entity with the specified original ID, Rollbase displays the following alert:
rbf_getPicklist()
Purpose
Returns items available for selected picklist field (including radio buttons and groups of check box fields) as a
JSON array. Each array entry has the elements name, id, and code. For fields that allow values in multiple
languages, pass a JSON object specifying which language's values to return in the options parameter. If the
values are not available in the request language, it will return the values for the tenant's base language. If the
specified language is not configured for the tenant, it will throw an error.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1101
Chapter 15: Reference
Syntax
rbf_getPicklist(objName, fieldName, mainValueId, callback, options)
Parameters
objName
The object integration name.
fieldName
The field integration name.
mainValueId
The ID of the main picklist item (optional, for dependent picklists only).
callback
The callback function that will receive a JSON array of picklist items as its first parameter.
options
An optional JSON object that sets the values of optional arguments. Currently this is only used for
setting langCode to a valid two-letter ISO language code, for example, {"langCode":"es"}.
Note: This API is supported in portals as well.
rbf_getClientIP()
Purpose
Retrieves the client IP address.
This API will be available for Rollbase Application pages, Portal pages (authenticated/un-authenticated), and
Setup pages.
Syntax
rbf_getClientIP()
Parameters
None
Return Value
IP address
Example
The following example retrieves the IP of the client as the page loads.
<script>
$(document).ready(function () {
1102 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Client-side AJAX API
yourFunction();
});
function yourFunction(){
var ip=rbf_getClientIP();
console.log("-------------------------->"+ip)
}
</script>
Note: This API is supported in portals as well.
rbf_isChecked()
Warning: Support for using this method with external objects (such as those mapped to external tables,
to OpenEdge Service objects, or through a D2C connection) is a beta feature. This method is supported
in production systems, except for external objects.
Purpose
Returns true if a checkbox with a given integration name is checked; false otherwise.
Syntax
rbf_isChecked(fieldName)
Parameters
fieldName
The integration name of checkbox field
Note: This API is supported in portals as well.
rbf_isEmpty()
Warning: Support for using this method with external objects (such as those mapped to external tables,
to OpenEdge Service objects, or through a D2C connection) is a beta feature. This method is supported
in production systems, except for external objects.
Purpose
Returns true if argument is null or empty string.
Syntax
rbf_isEmpty(arg)
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1103
Chapter 15: Reference
Parameters
arg
The argument to be tested
Note: This API is supported in portals as well.
Example
rbf_isEmpty() -> true
rbf_isEmpty(-1.23) -> false
rbf_isEmpty(0) -> true
rbf_isEmpty('') -> true
rbf_isEmpty(false) -> true
rbf_isEmpty("A") -> false
rbf_isEmpty("0") -> false
rbf_isSelected()
Warning: Support for using this method with external objects (such as those mapped to external tables,
to OpenEdge Service objects, or through a D2C connection) is a beta feature. This method is supported
in production systems, except for external objects.
Purpose
Returns true if record with given id is selected (check box checked) in list view.
Syntax
rbf_isSelected(recordId)
Parameters
recordId
The numeric ID of record
Note: This API is supported in portals as well.
rbf_isZero()
Warning: Support for using this method with external objects (such as those mapped to external tables,
to OpenEdge Service objects, or through a D2C connection) is a beta feature. This method is supported
in production systems, except for external objects.
1104 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Client-side AJAX API
Purpose
This function can be useful in validation scripts, it returns true if the argument is any of the following:
• null
• the number zero
• a value that cannot be converted into a number
Syntax
rbf_isZero(arg)
arg
The argument to be tested.
Note: This API is supported in portals as well.
Example
rbf_isZero() -> true
rbf_isZero(-1.23) -> false
rbf_isZero(0) -> true
rbf_isZero('') -> true
rbf_isZero(false) -> true
rbf_isZero("A") -> true
rbf_isZero("0") -> true
rbf_setChecked()
Warning: Support for using this method with external objects (such as those mapped to external tables,
to OpenEdge Service objects, or through a D2C connection) is a beta feature. This method is supported
in production systems, except for external objects.
Purpose
Sets the state of the checkbox field with the given integration name to checked (true) or unchecked (false).
It will invoke any existing onchange event handlers for that field.
Syntax
rbf_setChecked(fieldName, isChecked)
Parameters
fieldName
The integration name of the checkbox field
isChecked
true or false
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1105
Chapter 15: Reference
Note: This API is supported in portals as well.
rbf_setErrorsCallback()
Warning: Support for using this method with external objects (such as those mapped to external tables,
to OpenEdge Service objects, or through a D2C connection) is a beta feature. This method is supported
in production systems, except for external objects.
Purpose
Assign a callback function to be used when processing API errors, such as errors in SQL queries, etc. By
default the API uses the rbf_showInfoMessage() method to display error messages, but this behavior can
be customized.
Syntax
rbf_setErrorsCallback(callback)
Parameters
callback
The callback function, which will receive an error message as a first parameter and API name (which
caused the error) as second parameter
Note: This API is supported in portals as well.
Example
var callback = function(errMsg, apiName) {
alert("ERROR: "+errMsg+" in: "+apiName);
};
rbf_setErrorsCallback(callback);
rbf_setLookupFilter()
Warning: Support for using this method with external objects (such as those mapped to external tables,
to OpenEdge Service objects, or through a D2C connection) is a beta feature. This method is supported
in production systems, except for external objects.
Purpose
This function sets a filter on the selection of related records for a lookup field. This method only applies to
Selector type lookup fields and cannot be used for dependent lookups. This method can be used for dynamic
filtering of available lookup choices.
Syntax
rbf_setLookupFilter(fieldname, filterName, filterValue);
1106 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Client-side AJAX API
Parameters
fieldName
Integration name of the lookup field
filterName
Name of the related object field used for filtering
filterValue
Value of fields to display
Note: This API is supported in portals as well.
Return Value
Example
The call in the following example ensures that the selector window opening on the R12345 lookup field only
displays records where the value of the club_menber field equals true.
rbf_setLookupFilter('R12345', 'club_menber', 'true');
rbf_setSelected()
Warning: Support for using this method with external objects (such as those mapped to external tables,
to OpenEdge Service objects, or through a D2C connection) is a beta feature. This method is supported
in production systems, except for external objects.
Purpose
Selects/deselects record with given ID in list view.
Syntax
rbf_setSelected(recordId, selected)
Parameters
recordId
The numeric ID of record
selected
true or false
Note: This API is supported in portals as well.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1107
Chapter 15: Reference
Example
var x = rbf_isSelected(recordId);
rbf_setSelected(recordId, !x);
rbf_startServerDebugging()
Purpose
Starts server-side debugging. This API is used for debugging purposes.
Syntax
rbf_startServerDebugging(callback)
Parameters
callback
The function that is executed when server debugging operation is started. This doesn't receive any
parameters.
Note: This API is supported in portals as well.
Permissions
It is only available for Administrative users.
Example
rbf_startServerDebugging(function() {
alert("Start debugging server-side API"); });
rbf_stopServerDebugging()
Purpose
Stops server-side debugging process started by rbf_startServerDebugging() on page 1108. This API is used for
displaying the results of debugging.
Syntax
rbf_stopServerDebugging(callback)
Parameters
callback
The function that is executed when server debugging operation is completed. This receives a string
parameter that contains a summary of debug operations.
Note: Outputs from rbv_api.println() and similar functions are included and displayed as the
results of debugging.
1108 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Client-side AJAX API
Note: This API is supported in portals as well.
Permissions
It is only available for Administrative users.
Example
rbf_stopServerDebugging( function (debugMsg) {
alert('Stop debugging server-side API, Debug Messages: ' +debugMsg);
} );
rbf_sendHttpRequest
Purpose
Rollbase client-side API to provide end-users the ability to invoke RESTful web services from within a Rollbase
page. This API will be available for Rollbase Application pages and Portal pages and can be leveraged in
Custom Script Components. This API will be available in portal pages only if the AJAX calls are enabled for
portal users.
Note: This method can use server-side tokens ensuring that logged-in users do not see the resolved value
on client-side. You can achieve this by using the syntax {\u0021#tokenName}. This provides a very secure
solution when you need to use secret keys in API calls.
Syntax
rbf_sendHttpRequest(url, method, headers, params, body, options)
Parameters
url
The REST Service URL. This function argument is mandatory.
method
The HTTP method. This function argument is mandatory. The POST, GET, PUT, and DELETE HTTP
Methods are supported.
headers
The JSON object with key-value pairs to be forwarded as HTTP Request headers.
params
The JSON object with key-value pairs, wherein, each entry denotes HTTP Request parameter name
and parameter value.
body
The request payload as serialized string literal.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1109
Chapter 15: Reference
options
The JSON object with additional optional arguments as properties.
Property Name Description
callback Callback function handler. This API has
asynchronous behavior. The service response is
passed as an JSON object (function argument)
to this callback function. This JSON object
encapsulates the response status code, headers,
and payload.
errorCallback The error details will be passed as arguments to
this error callback handler. If this callback handler
is not configured, use the global error handler
function 'rbv_errorsCallback'.
userName On Rollbase server side, while establishing HTTP
connection to RESTful Service host, Rollbase
supports HTTP Basic Authentication. You must
pass the user-name details as this property value.
You can also set Rollbase token as the property
value. The Rollbase token will be resolved and
used in the Authorization header of the HTTP
request.
password On Rollbase server side, while establishing HTTP
connection to RESTful Service host, Rollbase
supports HTTP Basic Authentication. You must
pass password as this property value. You can
also set Rollbase token as property value. The
Rollbase token will be resolved and used in the
Authorization header of the HTTP request.
httpReadTimeout This property configures socket read timeout for
the HTTP connection in milliseconds. That default
value is 2 minutes. However, this can be
configured to a maximum of 8 minutes.
debug This property logs debug messages (tenant
specific) on Rollbase server-side, while relaying
service request and response.
timeout This property configures AJAX call timeout in
milliseconds. The default value is 5 minutes.
However, this can be configured to a maximum
of 15 minutes using this property. On exceeding
this period, AJAX call will timeout and result in a
timeout error response.
Note: This method is allowed only for REST service host white-listed by the administrator. Refer Editing
applications on page 109. The server-side token resolution is available for the CURR_USER , CURR_VISIT
(Portal Visitor) , SETTINGS, and CURR_CUSTM objects.
1110 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Client-side AJAX API
Limitations
As this API is primarily client-side, it deals with HTTP request and response payload content-types such as
text/plain, application/xml, and application/json.
HTTP requests with content-type multipart/form-data are not supported.
Tokens
You can use tokens as API arguments and enforce that these tokens can be evaluated on server side as a
part of API call. For this, you need to escape tokens. For example, a token like ‘{!SETTINGS.PASSWORD}’,
should be embedded in script as ‘{\u0021SETTINGS. PASSWORD }’. The other option is to use string
concatenation as ‘{‘+’!SETTINGS. PASSWORD }’.
Note: This API is supported in portals as well.
Example
<script>
function processExchangeRates(resp) {
if (resp.status == 200) {
var node = $.parseXML(resp.body); //parse xml string literal
var currRate = $(node).find('Rate').text();
}
}
rbf_sendHttpRequest('http://query.yahooapis.com/v1/public/yql', //url
'GET', //http method
{
'Accept': 'text/xml'
}, // headers
{
'q': 'select * from yahoo.finance.xchange where pair in ("USDEUR")',
'env': 'store://datatables.org/alltableswithkeys'
}, // params
null, //body
{
callback: processExchangeRates
} //options
);
</script>
rbf_invokeSystemRESTAPI()
Purpose
Rollbase client-side API to provide end-users the ability to invoke Rollbase REST APIs on the same instance
from a logged in UI session.
Note: This API is available only in New UI pages.
Syntax
rbf_invokeSystemRESTAPI(restMethod, httpMethod, headers, params, body, options)
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1111
Chapter 15: Reference
Parameters
restMethod
The rest method. This function argument is mandatory. See Rollbase REST Methods on page 1201
for more information on rest methods.
httpMethod
The HTTP method. This function argument is mandatory. The POST, GET, PUT, and DELETE HTTP
Methods are supported.
headers
The JSON object with key-value pairs to be forwarded as HTTP Request headers.
params
The JSON object with key-value pairs, wherein, each entry denotes HTTP Request parameter name
and parameter value.
body
The request payload as serialized string literal.
options
The JSON object with additional optional arguments as properties.
Property Name Description
callback Callback function handler. This API has
asynchronous behavior. The service response is
passed as an JSON object (function argument)
to this callback function. This JSON object
encapsulates the response status code, headers,
and payload.
errorCallback The error details will be passed as arguments to
this error callback handler. If this callback handler
is not configured, use the global error handler
function 'rbv_errorsCallback'.
userName On Rollbase server side, while establishing HTTP
connection to RESTful Service host, Rollbase
supports HTTP Basic Authentication. You must
pass the user-name details as this property value.
You can also set Rollbase token as the property
value. The Rollbase token will be resolved and
used in the Authorization header of the HTTP
request.
1112 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Client-side AJAX API
Property Name Description
password On Rollbase server side, while establishing HTTP
connection to RESTful Service host, Rollbase
supports HTTP Basic Authentication. You must
pass password as this property value. You can
also set Rollbase token as property value. The
Rollbase token will be resolved and used in the
Authorization header of the HTTP request.
httpReadTimeout This property configures socket read timeout for
the HTTP connection in milliseconds. That default
value is 2 minutes. However, this can be
configured to a maximum of 8 minutes.
debug This property logs debug messages (tenant
specific) on Rollbase server-side, while relaying
service request and response.
timeout This property configures AJAX call timeout in
milliseconds. The default value is 5 minutes.
However, this can be configured to a maximum
of 15 minutes using this property. On exceeding
this period, AJAX call will timeout and result in a
timeout error response.
Note: This API is supported in portals as well.
Example
<script>
rbf_addOnLoadMethod(onLoad);
function onLoad() {
var params = {};
params.objName = 'detSearch';
var body = '<?xml version="1.0" encoding="utf-8" ?>
<data objName="detSearch" useIds="false">
<Field name="name">detSearch_script_create_1</Field></data>';
rbf_invokeSystemRESTAPI('create', 'POST', null, params, body,
{'callback':function(response)
{ console.log(response);} }) }
</script>
Display Functions
The Rollbase JavaScript API functions in this section can be useful in customizing UI presentation of Rollbase
pages.
Note: All the display related APIs are supported in portals except for rbf_activatePageTab(),
rbf_getFieldContext(), rbf_getPageComponent(), rbf_getPageContext(), rbf_showMessage().
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1113
Chapter 15: Reference
rbf_activatePageTab()
Warning: Support for using this method with external objects (such as those mapped to external tables,
to OpenEdge Service objects, or through a D2C connection) is a beta feature. This method is supported
in production systems, except for external objects.
Purpose
Activate page-level tab with given index (only for pages where tabs are enabled).
Syntax
rbf_activatePageTab(tabIndex)
Parameters
tabIndex
The 0-based index of page level tab to be activated
Note: This API is not supported in portals.
rbf_getFieldContext()
Purpose
For any field in an object record form on a new, edit, status change, or quick create page, this function returns
a FieldContext object for that field. The FieldContext object encapsulates state and behavior details for the
associated field. See FieldContext on page 1132 for more information about the FieldContext object and its
interface.
Note: This API and the FieldContext object are only available in the New UI.
Syntax
rbf_getFieldContext(fieldIntegrationName)
Parameters
fieldIntegrationName
The integration name of the field
Note: This API is not supported in portals.
1114 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Client-side AJAX API
Example
The following example obtains the FieldContext object for a field with the integration name "city".
var cityFieldContext = rbf_getFieldContext('city');
rbf_getPageComponent()
Purpose
Charts, grids, and tabular reports are represented as PageComponent objects in the new UI. This function
returns a PageComponent object for a given component. The PageComponent object can then be used to
refresh an individual page component or to access its Kendo configuration object. See PageComponent on
page 1135 for more information about PageComponent and its interface.
Note: This API and the PageComponent object are only available in the New UI.
Syntax
rbf_getPageComponent(componentId)
Parameters
componentId
For charts and grids, the original ID of the section that contains the chart or grid (available in the
section's Properties menu). For reports, the original ID of the report (available in the System
Information section when viewing the report).
Note: This API is not supported in portals.
rbf_getPageContext()
Purpose
This function returns a PageContext object for the current page. The PageContext object encapsulates all state
and behavior of a page.. See PageContext on page 1136 for more information about the PageContext object and
its interface.
Note: This API and the PageContext object are only available in the New UI.
Syntax
rbf_getPageContext()
Parameters
None
Note: This API is not supported in portals.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1115
Chapter 15: Reference
Return value
The PageContext on page 1136 object for the current page.
Example
The following example sets a variable to the ID of the current page:
var pageId = rbf_getPageContext().getPageId();
rbf_getSectionIdByTitle()
Warning: Support for using this method with external objects (such as those mapped to external tables,
to OpenEdge Service objects, or through a D2C connection) is a beta feature. This method is supported
in production systems, except for external objects.
Purpose
This function finds ID of section with given title or null if section not found. This ID can be used in
rbf_setSectionCollapse and rbf_showOrHideSection API.
Important: For multi-lingual customers sectionTitle parameter must use customer's base language, not user
selected language.
Syntax
rbf_getSectionIdByTitle(sectionTitle)
Parameters
sectionTitle
Title of section on current page
Note: This API is supported in portals as well.
rbf_getViewSelector()
Warning: Support for using this method with external objects (such as those mapped to external tables,
to OpenEdge Service objects, or through a D2C connection) is a beta feature. This method is supported
in production systems, except for external objects.
Purpose
This function returns the view ID used by a lookup field for both auto-complete and pop-up selectors.
Syntax
rbf_getViewSelector(fieldName)
1116 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Client-side AJAX API
Parameters
fieldName
The integration name of lookup field
Note: This API is supported in portals as well.
rbf_growl()
Purpose
Displays a growl-type floating notification in the upper right side of the screen.
Warning: Support for using this method with external objects (such as those mapped to external tables,
to OpenEdge Service objects, or through a D2C connection) is a beta feature. This method is supported
in production systems, except for external objects.
Syntax
rbf_growl(title, message, type);
Parameters
title
Optional title to display. If none is specified, a default title will display.
message
The notification. If null or empty, the notification will not display.
type
One of info, success, error, or warn. If not specified, defaults to warn.
Note: This API is supported in portals as well.
rbf_growlError()
Purpose
Displays a growl-type floating notification in the upper right side of the screen. End-users have to close the
notification to dismiss it.
Warning: Support for using this method with external objects (such as those mapped to external tables,
to OpenEdge Service objects, or through a D2C connection) is a beta feature. This method is supported
in production systems, except for external objects.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1117
Chapter 15: Reference
Syntax
rbf_growlError(title, message);
Parameters
title
Optional title to display. If none is specified, a default title will display.
message
The notification. If null or empty, the notification will not display.
Note: This API is supported in portals as well.
rbf_hideGrowl()
Purpose
Hides a notification if one is being displayed.
Warning: Support for using this method with external objects (such as those mapped to external tables,
to OpenEdge Service objects, or through a D2C connection) is a beta feature. This method is supported
in production systems, except for external objects.
Syntax
rbf_hideGrowl();
Note: This API is supported in portals as well.
rbf_hideInfoMessage()
Warning: Support for using this method with external objects (such as those mapped to external tables,
to OpenEdge Service objects, or through a D2C connection) is a beta feature. This method is supported
in production systems, except for external objects.
Purpose
This function hides the status message at the top of the page. This method implementation calls rbf_hideGrowl()
on page 1118.
Note: This API is supported in portals as well.
1118 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Client-side AJAX API
Syntax
rbf_hideInfoMessage()
rbf_growlInfo()
Purpose
Displays a growl-type floating notification in the upper right side of the screen. The notification closes
automatically after approximately 3.5 seconds.
Warning: Support for using this method with external objects (such as those mapped to external tables,
to OpenEdge Service objects, or through a D2C connection) is a beta feature. This method is supported
in production systems, except for external objects.
Syntax
rbf_growlInfo(title, message);
Parameters
title
Optional title to display. If none is specified, a default title will display.
message
The notification. If null or empty, the notification will not display.
Note: This API is supported in portals as well.
rbf_growlSuccess()
Purpose
Displays a growl-type floating success notification in the upper right side of the screen. The notification closes
automatically after approximately 3.5 seconds.
Warning: Support for using this method with external objects (such as those mapped to external tables,
to OpenEdge Service objects, or through a D2C connection) is a beta feature. This method is supported
in production systems, except for external objects.
Syntax
rbf_growlSuccess(title, message);
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1119
Chapter 15: Reference
Parameters
title
Optional title to display. If none is specified, a default title will display.
message
The notification. If null or empty, the notification will not display.
Note: This API is supported in portals as well.
Example
rbf_growlSuccess(null,
"Revised currency exchange rate applied.");
rbf_growlWarning()
Purpose
Displays a growl-type floating notification in the upper right side of the screen. End-users have to close the
notification to dismiss it.
Warning: Support for using this method with external objects (such as those mapped to external tables,
to OpenEdge Service objects, or through a D2C connection) is a beta feature. This method is supported
in production systems, except for external objects.
Syntax
rbf_growlWarning(title, message);
Parameters
title
Optional title to display. If none is specified, a default title will display.
message
The notification. If null or empty, the notification will not display.
Note: This API is supported in portals as well.
rbf_showInfoMessage()
Warning: Support for using this method with external objects (such as those mapped to external tables,
to OpenEdge Service objects, or through a D2C connection) is a beta feature. This method is supported
in production systems, except for external objects.
1120 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Client-side AJAX API
Purpose
Displays a status message on the page.
Syntax
rbf_showInfoMessage(message, isError)
Parameters
message
The message text
isError
Set as Boolean true in case of error messages, otherwise false.
Note: This API is supported in portals as well.
rbf_showOrHideField()
Warning: Support for using this method with external objects (such as those mapped to external tables,
to OpenEdge Service objects, or through a D2C connection) is a beta feature. This method is supported
in production systems, except for external objects.
Purpose
This function shows or hides a field and its label. It will have no effect if the field is not shown on the page. On
view pages, this API can be used in the page’s onLoad script; on edit pages, it can be used in any event
handling code.
Syntax
rbf_showOrHideField(fieldName, showField, doNotHideResponsiveColumn)
Parameters
fieldName
The integration name of the field
showField
If true, show the field and its label. If false, hide the field and its label.
doNotHideResponsiveColumn
Optional. If true, Rollbase hides only the value of the field, not the column itself. The column for
the hidden field maintains its position regardless of the screen size. If false, Rollbase hides both
the value of the field and its column. The value in the next column will take its position. Defaults to
false.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1121
Chapter 15: Reference
Note: This API is supported in portals as well.
Examples
The following examples show the behavior resulting from different options for showOrHideField(). In these
examples, the view page is configured for four columns. The field to show or hide is Status (with the integration
name t_status):
• Result of showOrHideField("t_status", true):
• Result of showOrHideField("t_status", false, true). The field's position is maintained in the
row:
• Result of showOrHideField("t_status", false, false). The other fields in the row shift left, while
the following rows remain the same:
• Result of showOrHideField("t_status", true) on a narrower screen, where the four columns have
collapsed to two columns:
• Result of showOrHideField("t_status", false, false) with two columns. The other field in the
row, Tags, shifts left, while the following rows remain the same:
1122 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Client-side AJAX API
rbf_showOrHidePageTab()
Warning: Support for using this method with external objects (such as those mapped to external tables,
to OpenEdge Service objects, or through a D2C connection) is a beta feature. This method is supported
in production systems, except for external objects.
Purpose
Show or hide page-level tab with given index (only for pages where tabs are enabled).
Syntax
rbf_showOrHidePageTab(tabIndex, showTab)
Parameters
tabIndex
The 0-based index of page level tab to be activated
showTab
If true, show tab, if false, hide tab
Note: This API is supported in portals as well.
rbf_showOrHideSection()
Warning: Support for using this method with external objects (such as those mapped to external tables,
to OpenEdge Service objects, or through a D2C connection) is a beta feature. This method is supported
in production systems, except for external objects.
Purpose
This function hides or shows a Page's section. It will have no effect if the section does not exist.
The ID for any section can be found by selecting that section while editing the page in the Page Editor. Highlight
the Page section by clicking on its header and use the "Original ID" parameter shown in the Properties box.
You can also use rbf_getSectionIdByTitle() on page 1116.
Syntax
rbf_showOrHideSection(sectionId, showSection)
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1123
Chapter 15: Reference
Parameters
sectionId
The original ID of page's section (can be found in Page Editor)
showSection
If true, show section, if false, hide section
Note: This API is supported in portals as well.
rbf_setSectionCollapse()
Warning: Support for using this method with external objects (such as those mapped to external tables,
to OpenEdge Service objects, or through a D2C connection) is a beta feature. This method is supported
in production systems, except for external objects.
Purpose
This function collapses or expands the Page's section. It will have no effect if the section does not exist or is
non-collapsible.
Syntax
rbf_setSectionCollapse(sectionId, collapsed)
Parameters
sectionId
Original ID of Page's section (can be found in Page Editor)
collapsed
If true, collapse section, if false, expand section
Note: This API is supported in portals as well.
rbf_setViewSelector()
Warning: Support for using this method with external objects (such as those mapped to external tables,
to OpenEdge Service objects, or through a D2C connection) is a beta feature. This method is supported
in production systems, except for external objects.
Purpose
This function sets the view ID used by a lookup field for both auto-complete and pop-up selectors.
Important: This function cannot be used on dependent lookups. This function only apply for "Selector" style
lookup fields.
1124 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Client-side AJAX API
Syntax
rbf_setViewSelector(fieldName, selectorViewId)
Parameters
fieldName
The integration name of lookup field
selectorViewId
ID of view to use
Note: This API is supported in portals as well.
User session data
The functions in this section allow you to set, retrieve, and remove custom user session data. Rollbase stores
this data as key/value pairs and it is available for the duration of the user session.
Custom user session data is useful when you want to visit multiple application pages and have each of those
pages display data related to the same record or in the same context. For example, you might store the record
name in a script component on a view page and retrieve it to filter the view in a script component on a record
list page.
You can use server-side APIs as well as client-side APIs to access the same user session data. See User
session data API on page 1027 for information about server-side user session data APIs.
Note: The user session data related APIs are not supported in portals.
rbf_setSessionData()
Purpose
This function sets user session data as a key/value pair. This data is stored in the Rollbase session and can
be accessed using the function rbf_getSessionData() on page 1127 and removed using the function
rbf_removeSessionData() on page 1129. The maximum number of key/value pairs is 50. If you set a value for
an existing key, the new value overrides the previous value.
If this function raises an error, Rollbase sets the HTTP status to 500 and invokes the callback function provided
via rbf_setErrorsCallback() on page 1106 and passes that function one of the following messages:
• Empty Key Received — No input was passed
• Invalid Input — Input was in the wrong format
• Limit Violation. Max Allowed: 50 keys reached — User has already stored the maximum of
50 key/value pairs
Note: If this function call results in an error, and you have not configured a callback function using
rbf_setErrorsCallback(), you will still see the HTTP status of 500 but will not see the reason for the
error.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1125
Chapter 15: Reference
Syntax
rbf_setSessionData(key, value, callback);
Parameters
key
A string that is the lookup key for user session data. The maximum length of a key is 50 characters.
value
The value associated with key. The value can be a boolean, number, string (maximum length is 1000
characters), or null (where null is the value).
callback
A function that takes a single data value. This parameter is optional; if it is not passed, the status of
the function call will appear in the console but you will not be able to access the return value.
Note: This API is not supported in portals.
Return value
If successful, passes the string "Session Data set successfully" to callback and sets the HTTP
status to 200.
Example
The following example sets a key/value pair:
<script>
var callback = function(errMsg, apiName) {
alert("ERROR: "+errMsg+" in: "+apiName);
};
rbf_setErrorsCallback(callback);
var handleSessionData = function (response) {
if(console){
console.log("**** Processing handleSessionData ****");
console.log("Response is: ", response);
}
}
rbf_setSessionData("name1", "John", handleSessionData);
</script>
The following example passes no input and results in an error:
<script>
var callback = function(errMsg, apiName) {
alert("ERROR: "+errMsg+" in: "+apiName);
};
rbf_setErrorsCallback(callback);
var handleSessionData = function (response) {
if(console){
console.log("**** Processing handleSessionData ****");
console.log("Response is: ", response);
}
}
rbf_setSessionData();
</script>
1126 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Client-side AJAX API
Because no input was passed, Rollbase displays the following alert:
rbf_getSessionData()
Purpose
For custom user session data, this function returns the value for the specified key and passes it to the specified
callback function. See User session data on page 1125 for more information about custom user session data.
If this function raises an error, Rollbase sets the HTTP status to 500 and invokes the callback function provided
via rbf_setErrorsCallback() on page 1106 and passes that function one of the following messages:
• Empty key received! — No key parameter was passed
• No Mappings Set for [key] — There is no value associated with the specified key or there is no
custom session data to retrieve
Note: If this function call results in an error, and you have not configured a callback function using
rbf_setErrorsCallback(), you will still see the HTTP status of 500 but will not see the reason for the
error.
Syntax
rbf_getSessionData(key, callback);
Parameters
key
A string that is the lookup key for user session data. The maximum length of a key is 50 characters.
callback
A function that takes a single data value. This parameter is optional; if it is not passed, the status of
the function call will appear in the console but you will not be able to access the return value.
Note: This API is not supported in portals.
Return value
If successful, passes the value associated with that key (JavaScript primitive) to callback function and sets
the HTTP status to 200
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1127
Chapter 15: Reference
Example
The following example retrieves the value for the specified key and outputs it to the console. If there is an error,
the callback function displays an alert with an error message:
<script>
var callback = function(errMsg, apiName) {
alert("ERROR: "+errMsg+" in: "+apiName);
};
rbf_setErrorsCallback(callback);
var handleSessionData = function (dataValue) {
if(console){
console.log("**** Processing handleSessionData ****");
console.log("Data Value is: ", dataValue);
}
}
rbf_getSessionData("name1", handleSessionData);
</script>
If the specified key does not exist, Rollbase displays the following alert:
rbf_getAllSessionData()
Purpose
For custom user session data, this function returns a hashmap of all key/value pairs for that user and passes
it to the specified callback function. See User session data on page 1125 for more information about custom user
session data.
If this function raises an error, Rollbase sets the HTTP status to 500 and invokes the callback function provided
via rbf_setErrorsCallback() on page 1106 and passes that function the following message:
• No Custom Session Data is Set by User — No custom session data exists for the user
Note: If this function call results in an error, and you have not configured a callback function using
rbf_setErrorsCallback(), you will still see the HTTP status of 500 but will not see the reason for the
error.
Syntax
rbf_getAllSessionData(callback);
Parameters
callback
A function that takes a single data value. This parameter is optional; if it is not passed, the status of
the function call will appear in the console but you will not be able to access the return value.
1128 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Client-side AJAX API
Note: This API is not supported in portals.
Return value
If successful, passes a hashmap of all existing key/value pairs to callback function and sets the HTTP status
to 200
Example
The following example retrieves a hashmap of all key/value pairs and outputs it to the console. If there is an
error, the callback function displays an alert with an error message:
<script>
var callback = function(errMsg, apiName) {
alert("ERROR: "+errMsg+" in: "+apiName);
};
rbf_setErrorsCallback(callback);
var handleSessionData = function (dataValue) {
if(console){
console.log("**** Processing handleSessionData ****");
console.log("Data Value is: ", dataValue);
}
}
rbf_getAllSessionData(handleSessionData);
</script>
Sample output for this example:
Data Value is: Object {name2: "Jim", name1: "John"}
rbf_removeSessionData()
Purpose
This function removes the user session data for the specified key.
If this function raises an error, Rollbase sets the HTTP status to 500 and invokes the callback function provided
via rbf_setErrorsCallback() on page 1106 and passes that function one of the following messages:
• Empty key received! — No key parameter was passed
• No Mappings Set for [key] — There is no value associated with the specified key
Note: If this function call results in an error, and you have not configured a callback function using
rbf_setErrorsCallback(), you will still see the HTTP status of 500 but will not see the reason for the
error.
Syntax
rbf_removeSessionData(key, callback);
Parameters
key
A string that is the key for a key/value pair of stored custom session data
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1129
Chapter 15: Reference
callback
A function that takes a single data value. This parameter is optional; if it is not passed, the HTTP
status will appear in the console but no return value is passed.
Note: This API is not supported in portals.
Return value
If successful, sets the HTTP status to 200 and passes the string OK to callback as the first argument
Example
The following example removes the custom user session data associated with the key "name1":
<script>
var callback = function(errMsg, apiName) {
alert("ERROR: "+errMsg+" in: "+apiName);
};
rbf_setErrorsCallback(callback);
var handleSessionData = function (returnValue) {
if(console){
console.log("**** Processing handleSessionData ****");
console.log("Response is " +returnValue);
}
}
rbf_removeSessionData("name1", handleSessionData);
</script>
rbf_removeAllSessionData()
Purpose
This function removes all session data for the user.
If this function raises an error, Rollbase sets the HTTP status to 500 and invokes the callback function provided
via rbf_setErrorsCallback() on page 1106 and passes that function the following message:
• No Custom Session Data is Set by User — No session data exists for the user
Note: If this function call results in an error, and you have not configured a callback function using
rbf_setErrorsCallback(), you will still see the HTTP status of 500 but will not see the reason for the
error.
Syntax
rbf_removeAllSessionData(callback);
Parameters
callback
A function that takes a single data value. This parameter is optional; if it is not passed, the status of
the function call will appear in the console but you will not be able to access the return value.
Note: This API is not supported in portals.
1130 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Client-side JavaScript
Sets the HTTP status to 200 and passes the string OK to callback as the first argument.
Example
The following example removes all session data for the user:
<script>
var callback = function(errMsg, apiName) {
alert("ERROR: "+errMsg+" in: "+apiName);
};
rbf_setErrorsCallback(callback);
var handleSessionData = function (returnValue) {
if(console){
console.log("**** Processing handleSessionData ****");
console.log("Response is " +returnValue);
}
}
rbf_removeAllSessionData(handleSessionData);
</script>
Client-side JavaScript
The client-side JavaScript API includes functions, objects with interfaces, properties, and events. You can use
the JavaScript API anywhere you can create a client-side script, for example, in a script component on a page
or in a custom header. See Adding business logic on page 183 for information about where you can use
client-side scripts. See Programmatic client-side customization on page 507 for examples of script components.
Note:
The methods in this section apply to the new UI, not the classic UI. Most Rollbase tenants are using the new
UI. However, tenants on older Private Cloud installations might still be using the classic UI.
These methods are not supported in portals.
Executing a script before the UI starts
You can add custom scripts to the sidebar and to the header and footer for your application. Typically, these
scripts execute after the UI is rendered so that they can access, modify, or add elements to the page. However,
there might be situations where you need to execute code before the UI is rendered. For example, you might
want to modify some rb.newui.options. Rollbase allows you to specify one script in the custom sidebar to
be executed before the UI starts. The script tag for that script must include id="executeBeforeUIStarts".
The script will be executed only once and it will be executed before the UI starts rendering. A custom sidebar
can also contain other scripts, which will be executed after the UI has rendered.
The following example is a script in a custom sidebar that will execute before the UI starts:
<script id="executeBeforeUIStarts">
try {
if ( window.rb !== undefined && window.rb.newui !== undefined ) {
console.log("*** Executing Custom Sidebar for New UI");
rb.newui.options.filters.showAdvancedFilterTypes = false;
}
}
catch (e) {alert ('Error in custom sidebar code' + e);
}
</script>
Debugging scripts
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1131
Chapter 15: Reference
You can use the debugger statement to set a breakpoint in a script. This causes execution to pause. The
following example sets a breakpoint in a script:
<script id="executeBeforeUIStarts">
try {
if ( window.rb !== undefined && window.rb.newui !== undefined ) {
console.log("*** Executing Custom Sidebar for New UI");
debugger; // set breakpoint
rb.newui.options.filters.showAdvancedFilterTypes = false;
}
}
catch (e) {alert ('Error in custom sidebar code' + e);
}
</script>
Objects
Rollbase uses JavaScript objects to represent certain aspects of the user interface and environment in which
it is running. Each object described in this section can be accessed via a client-side AJAX API as indicated.
You can use these objects in client-side scripts.
Note:
The methods in this section apply to the new UI, not the classic UI. Most Rollbase tenants are using the new
UI. However, tenants on older Private Cloud installations might still be using the classic UI.
These methods are not supported in portals.
FieldContext
Purpose
For any field in an object record form on a new, edit, status change, or quick create page, a FieldContext
object encapsulates state and behavior details for the associated field. The FieldContext object is only
available in the New UI. You can access a FieldContext object using the client-side function
rbf_getFieldContext() on page 1114.
Note:
The methods in this section apply to the new UI, not the classic UI. Most Rollbase tenants are using the new
UI. However, tenants on older Private Cloud installations might still be using the classic UI.
These methods are not supported in portals.
Interface
The following functions return information about the state of the field:
• getNode() — Returns a jQuery object for the HTML control (input, select, textarea, etc.)
• getKendoConfig() — Returns the Kendo configuration object for the field (if the field is a Kendo control).
Progress recommends using this function to access the Kendo configuration object for a field. It is faster
and easier than using other methods, and it uses wrappers provided by Rollbase instead of working directly
with the page DOM.
• getFieldType() — Returns a string identifier for the field type, for example,'IntInput' for Integer
fields
1132 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Client-side JavaScript
• getFormNode() — Returns a jQuery node reference for the form element in t\he page DOM
• getContainer() — Returns a jQuery object for the root container element that holds the field control
and its related DOM elements
The following functions return information about and allow you to specify the field's behavior:
• validate() — Runs client-side validation against the field
• enable(isEnabled) — Toggles whether the field is enabled or disabled.
• show() — Shows the field
• hide() — Hides the field
• focus() — Gives focus to the field
• isRequiredField() — Returns true if the field is marked as a required form field, otherwise returns
false.
• getValue() — Returns the field's current value
• setValue(value) — Sets the field's value to value
• addOnChangeHandler(handlerFunc) — Adds the change handler function handlerFunc to the field
• getInitialValue() — Returns the initial value of the form field when the form page was rendered
• hasValueChanged() — Returns true if the field value was modified on the form page
• getPicklistCode() — Returns the integration code of the selected option for a picklist, multi-picklist,
checkbox group, or radio buttons. When multiple options are selected, returns an array of integration codes.
GridControl
Purpose
GridControl is a client-side JavaScript object that represents a grid control on an application page.
Note: The GridControl component and its interface are only available for the revised grid control introduced
in Rollbase 4.3. You can enable/disable the revised grid control on the Preferences setup page.
Access a GridControl in one of two ways:
• The client-side function rbf_getPageComponent(componentId), where componentId is the original ID of
the GridControl.
• The client-side function rbf_getGridControlComponent(gridNo), where gridNo is the order in which this
GridControl component appears on the page.
Interface
The GridControl component has the following public interface:
• addEventListener(eventType,handler) — Registers an event listener for the given event type
• addGridRow() — Adds a new grid row to the GridControl
• deleteGridRow(rowIndex) — Removes the GridRow at the specified row index
• getContentElement() — Returns a jQuery object for the root element housing the GridControl
component
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1133
Chapter 15: Reference
• getFieldCell(rowIndex, fieldName) — Returns a jQuery object of the field container element where
the field is identified by rowIndex and fieldName
• getGridControlSectionToolbarEl() — Returns a jQuery object for the GridControl section toolbar
element
• getGridControlToolbar() — Returns a jQuery object for the GridControl toolbar element
• getGridControlToolbarEl() — Returns a Kendo Toolbar configuration object for the GridControl
toolbar
• getGridNumber() — Returns the order of the GridControl component on the page
• getGridRow(rowIndex) — Returns the GridRow object at the specified row index, where rowIndex
is the number of the row (the first row has the rowIndex of 0). See GridRow on page 1135 for more information.
• getId() — Returns the GridControl component's PageCell's ID
• getKendoConfig() — Returns the Kendo Grid configuration object for the GridControl component
• getLastModifiedField() — Returns the FieldContext object of the last modified field. See
FieldContext on page 1132 for more information.
• getMaxRowIndex() — Returns the number of grid rows in the GridControl component
• getOriginalId() — Returns the GridControl component's PageCell's originalID
• removeEventListener(eventType,handler) — Unregisters an event listener for the specified
eventType
• showGridTotals() — Computes and shows grid totals for each TotalBy column in the GridControl
component
• sumGridColumn(fieldName) — Computes and shows the grid total for the specified GridControl
column as identified by fieldName
Example
The following example returns the original ID of the first grid control on the page.
<script>
rbf_getGridControlComponent(0).getOriginalId();
</script>
GridFieldContext
Purpose
For any field in a grid control, a GridFieldContext object encapsulates state and behavior details for the
associated field. The GridFieldContext object is only available in the New UI. You can access a
GridFieldContext object using the client-side function rbf_getGridFieldContext() on page 1079. The interface
of GridFieldContext includes all functions defined for FieldContext on page 1132. See rbf_getGridFieldContext()
on page 1079 for an example of accessing a GridFieldContext and executing one of its functions.
Interface
The following functions return information about the state of the field:
• isGridControlField() — Returns true if the associated field is in a grid control. Otherwise returns
false.
1134 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Client-side JavaScript
• getGridRow() — Returns the GridRow on page 1135 object for the associated field.
• getGridFieldData() — Returns a JSON object representing the value of the associated field.
• getGridComponent() — Returns the GridControl on page 1133 object to which this field belongs.
GridRow
Purpose
GridRow is a client-side JavaScript object that represents a row in a grid control on an application page.
Note: The GridRow component and its interface are only available for the revised grid control introduced in
Rollbase 4.3. You can enable/disable the revised grid control on the Preferences setup page.
Access a GridRow from a GridControl by calling the method getGridRow(rowIndex), where rowIndex
is the number of the row (the first row has the rowIndex of 0). See GridControl on page 1133 for more information.
Interface
The GridRow component has the following public interface:
• getData() — Returns GridRow data in serialized JSON format
• getField(fieldName) — Returns the FieldContext object for the specified field in the row where the
field is identified by its integration name.. See FieldContext on page 1132 for more information.
• getFieldCell(fieldName) — Returns a jQuery object of the field container element where the field is
identified by its integration name.
• getFieldData(fieldName) — Returns field data in serialized JSON format where the field is identified
by its integration name.
• getIndex() — Returns the row Index of this GridRow
• getRecordId() — Returns the GridRow record's record ID. The value is -1 for new GridRow records.
Example
The following example returns the value of the field with the integration name "name" for the first row of the
first grid on the page .
<script>
rbf_getGridControlComponent(0).getGridRow(0).getFieldData("name");
</script>
PageComponent
Purpose
PageComponent is a client-side JavaScript object that represents a component on an application page. Charts,
grids, and tabular reports are all represented as PageComponent objects in the new UI. You can use a
PageComponent object's interface to refresh an individual PageComponent or to access its Kendo configuration
object. Use the client-side function rbf_getPageComponent() on page 1115 to access a specific PageComponent.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1135
Chapter 15: Reference
Note:
The methods in this section apply to the new UI, not the classic UI. Most Rollbase tenants are using the new
UI. However, tenants on older Private Cloud installations might still be using the classic UI.
These methods are not supported in portals.
Interface
You can refresh an individual PageComponent without refreshing its entire page. Use the following methods
to refresh a PageComponent:
• refresh() — Refreshes an individual page component on an application page. For a report, refreshes
both the chart and the grid rendered as part of the report.
• refreshChart() — For a report, refreshes only the chart rendered as part of the report
• refreshGrid() — For a report, refreshes only the grid rendered as part of the report
You can access the Kendo configuration object for a grid or a report using the following method:
• getKendoConfig() — For a grid, returns the Kendo configuration object for the grid. For a report, returns
the Kendo configuration object for the grid rendered as part of the report
Example
The following example refreshes a chart component and a grid component every six seconds. You would add
this script to an HTML or script component in the page editor.
<script>
var refreshPageComponents = function {
var chartComp = rbf_getPageComponent(530939);
if (chartComp) {
chartComp.refresh();
}
var gridComp = rbf_getPageComponent(246070);
if (gridComp) {
gridComp.refresh();
}
}
window.setInterval(refreshPageComponents, 6000);
</script>
PageContext
Purpose
A PageContext object encapsulates all state and behavior of a page. This is the root level context object from
which you can access other top level objects such as PageLocalization. The PageContext object is only
available in the New UI. You can access a PageContext object using the client-side function
rbf_getPageContext() on page 1115.
Interface
The following functions return information about the state of the page or return components on the page:
• getPageType() — Returns an integer identifier for the current page. All page identifiers are defined as
properties of rb.newui.PAGE_TYPES. This API can be leveraged to have custom behavior specific to a
1136 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Client-side JavaScript
given page, for example, to differentiate between a new and edit page to set a default value for a field in
new pages.
Page types are defined as follows:
rb.newui.PAGE_TYPES = {
GENERIC : 0,
VIEW : 1,
EDIT : 2,
NEW : 3,
SEARCH : 4,
SEARCH_RESULTS : 5,
STATUS : 6,
SELECTOR : 7,
EMAIL_SELECTOR : 8,// Used as substitution to TYPE_SELECTOR
TREE_SELECTOR : 9,
IMPORT : 10,
TEMPLATES : 12,
REP_LIST : 13,
REPORT : 14,
LOGIN : 16,
MASS_UPDATE : 17,
NEW_QUICK : 18,
CUSTOM_PAGE : 19,
WEB_LINK : 20,
QUESTIONS : 21,
LIST : 22,// List of records
SURVEY : 23,// Take survey
EMBED_QC : 24,
R_BIN_VIEW : 25
};
• getPageId() — Returns the page ID
• getPageTheme() — Returns a string identifier for the currently set page theme
• getLanguage() — Returns a string identifier for the currently set page language, for example, "en" for
English.
• getPageLocalization() — Returns the PageLocalization object for the page
• getLocalizedMessage(langResKey,params) — Returns the externalized string label for the specified
language resource key. If the externalized string is parameterized, it will replace all param tokens with values
passed in the params argument.
• getSection(sectionId) — Returns the Section object for the page section identified by sectionID,
which is the original ID of the section
• getFormDetails(formName) — Returns the FormContext object identified by the formName, where
formName is one of:
• rb.newui.util.EDIT_FORM_NAME — The form name for a record form
• rb.newui.util.INLINE_FORM_NAME — The form name for an inline edit form
This is currently only available for record forms and inline edit forms.
• getPageConstructionLog() — Returns the PageConstructionLog object
• getCanvasEl() — Returns the jQuery object for the root canvas element that renders all the page content.
Progress recommends using this method to run any jQuery selectors.
• getPageToolbar() — Returns the PageToolbar on page 1139 object
• hasSessionExpired() — Returns true if the user session has expired, otherwise returns false.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1137
Chapter 15: Reference
• getCurrentUITemplate() — Returns the CurrentUITemplate on page 1139 object.
The following functions return information about and allow you to specify the page's behavior:
• printPageConstructionLog() — Prints the page construction log with timing details onto the console
• isPageDirty() — Returns true if the page has an object record form with modifications
• isRedirectedOnServerValidation() — Returns true to identify when a user is redirected on
submitting an object record form because it failed server-side validations
• isDialogPage() — Returns true if the current page is rendered in a dialog, for example, a quick create
page
The following class methods control whether Rollbase notifies the user upon navigating away from a page with
unsaved changes. See onLeavingDirtyPage on page 1151 for information about the property that has the same
effect.
• addDirtyPageNotifier() — Enables notification when a user tries to navigate from a page with unsaved
changes. Example: rb.newui.page.PageContext.addDirtyPageNotifier();
• removeDirtyPageNotifier() — Disables notification when a user tries to navigate from a page with
unsaved changes. Example: rb.newui.page.PageContext.removeDirtyPageNotifier();
PageLocalization
Purpose
A PageLocalization object encapsulates the settings on a user's My Localization Settings page. The
PageLocalization object is only available in the New UI. You can access a PageLocalization object
using the PageContext function getPageLocalization(). See PageContext on page 1136 for details.
Interface
Unless indicated otherwise, all of the following methods return the format specified in the user's localization
settings.
• getDateFormat() — Returns a string representing the date format pattern, for example, "MM/dd/yyyy"
• getDateTimeFormat() — Returns a string representing the date/time format pattern, for example, "MMM
d, yyyy, h:mm tt"
• getLongDateFormat() — Returns a string representing the long date format pattern, for example, "dddd,
MMMM d, yyyy"
• getLongDateTimeFormat() — Returns a string representing the long date/time format pattern, for
example, "dddd, MMMM d, yyyy 'at' h:mm tt"
• getTimeFormat() — Returns a string representing the time format pattern, for example, "h:mm tt"
• getDateEditFormat() — Returns a string representing the date format pattern used on form pages
(new, edit, quick create, status change) when showing Date field values in input widgets. This format is not
in the user's localization settings and depends on the locale.
• getDateTimeEditFormat() — Returns a string representing the date/time format pattern used on form
pages (new, edit, quick create, status change) when showing DateTime field values in input widgets. This
format is not in the user's localization settings and depends on the locale.
1138 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Client-side JavaScript
PageToolbar
Purpose
PageToolbar is a client-side JavaScript object that represents the page toolbar on an application page. A
page toolbar contains buttons. Use the PageContext on page 1136 function getPageToolbar() to access the
PageToolbar object.
Note:
The methods in this section apply to the new UI, not the classic UI. Most Rollbase tenants are using the new
UI. However, tenants on older Private Cloud installations might still be using the classic UI.
These methods are not supported in portals.
Interface
PageToolbar supports the following functions:
• getItemByName(itemName) — Returns a jQuery object representing the button with the specified name
• getItemsByClassName(className) — Returns a set of jQuery objects representing all buttons in the
page toolbar with the CSS class identifier as specified by the argument className. Currently, all page
toolbar buttons have CSS class identifier "marker-pageToolbar-action".
• getKendoConfig() — Returns the Kendo Toolbar configuration object for the page toolbar
• getNode() — Returns a jQuery object representing the page toolbar
• showOrHideItem(itemName, show) — Shows or hides the button with the specified name. If the show
parameter is true, shows the button. If the show parameter is false, hides the button.
Examples
The following example returns a set of jQuery objects for all of the buttons in the page toolbar:
rbf_getPageContext().getPageToolbar().getItemsByClassName("marker-pageToolbar-action");
The following example hides the button with the specified name:
rbf_getPageContext().getPageToolbar().showOrHideItem("Button_1", false);
CurrentUITemplate
CurrentUITemplate is a client-side JavaScript object that represents the current UI template on an application
page. Use the PageContext on page 1136 function getCurrentUITemplate() to access the
CurrentUITemplate object.
Note: The methods in this section apply to the new UI, not the classic UI. Most Rollbase tenants are using
the new UI. However, tenants on older Private Cloud installations might still be using the classic UI.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1139
Chapter 15: Reference
Interface
CurrentUITemplate supports the following functions:
• getType() — Returns the current UI Blueprint type.
• getTypeName() — Returns the current UI Blueprint name.
• getCssIdentifier() — Returns the CSS classname for the current UI Blueprint.
Example
For the "Modern-Vertical Menus" UI Blueprint, the CurrentUITemplate functions return the following output:
rbf_getPageContext().getCurrentUITemplate().getType() - Returns 2
rbf_getPageContext().getCurrentUITemplate().getCssIdentifier()- Returns
"rbs-ui-template-type-2"
rbf_getPageContext().getCurrentUITemplate().getTypeName()- Returns
"Modern - Vertical Menus"
Functions
The functions described in this section can be run in client-side scripts.
Note:
The methods in this section apply to the new UI, not the classic UI. Most Rollbase tenants are using the new
UI. However, tenants on older Private Cloud installations might still be using the classic UI.
These methods are not supported in portals.
addEventListener()
Purpose
Adds an event listener for a custom event. You can use this function to listen for Rollbase custom events. See
Custom events on page 1154 for a description of custom events in Rollbase.
Note: If your applications contain any script components that execute on the document.ready event, they
will no longer behave in the same way because document ready events can get delivered before components
are rendered on the page. Instead, you should replace the document.ready event with a call to
addEventListener() on the rbs_pageRender custom event as shown below.
Syntax
rb.newui.util.addEventListener(event, handler);
Parameters
event
The event to listen for
1140 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Client-side JavaScript
handler
The function that will handle the event
Return value
None
Example
The following example creates a listener for the rbs_pageRender custom event.
Note:
This method applies to the new UI, not the classic UI. Most Rollbase tenants are using the new UI. However,
tenants on older Private Cloud installations might still be using the classic UI.
This method is not supported in portals.
<script>
try {
if (!rbf_isNewUI()) {
throw 'This Script is written specific to New UI Context';
}
var onPageRender = function (event) {
if(console){
console.log("**** Processing event rbs_pageRender ****");
}
};
rb.newui.util.addEventListener(rb.newui.util.customEvents.rbs_pageRender, onPageRender);
}
catch (err) {
if (console) {
console.log(err);
}
}
</script>
rbf_isNewUI()
Purpose
A check used to guard NewUI specific functions.
Note:
If your Rollbase application pages are rendered in both ClassicUI and NewUI (selectively for different subset
of users), then all NewUI specific client-side SDK functions/features should be guarded with this check.
This method is not supported in portals.
Syntax
rbf_isNewUI()
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1141
Chapter 15: Reference
Parameters
None
Example
The following example turns off the direction attribute to all paragraph elements inside Rich Text Editor.
<script>
try {
if (!rbf_isNewUI()) {
throw 'This Script is written for New UI';
}
//Set to false to turned this featured off.. Default it is enabled
rb.newui.options.richEditor.addAutoDirectionAttribute = false;
}
catch (err) {
if (console) {
console.log(err);
}
}
</script>
isMobile()
Purpose
Detects whether Rollbase is running on a mobile device (tablet or smart phone).
Note:
This method applies to the new UI, not the classic UI. Most Rollbase tenants are using the new UI. However,
tenants on older Private Cloud installations might still be using the classic UI.
This method is not supported in portals.
Syntax
rb.newui.util.isMobile()
Parameters
None
Return value
Returns true if the device is mobile. Otherwise returns false.
isTablet()
Purpose
Detects whether Rollbase is running on a tablet.
1142 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Client-side JavaScript
Note:
This method applies to the new UI, not the classic UI. Most Rollbase tenants are using the new UI. However,
tenants on older Private Cloud installations might still be using the classic UI.
This method is not supported in portals.
Syntax
rb.newui.util.isTablet()
Parameters
None
Return value
Returns true if the device is a tablet. Otherwise returns false.
isSmartPhone()
Purpose
Detects whether Rollbase is running on a smart phone.
Note:
This method applies to the new UI, not the classic UI. Most Rollbase tenants are using the new UI. However,
tenants on older Private Cloud installations might still be using the classic UI.
This method is not supported in portals.
Syntax
rb.newui.util.isSmartPhone()
Parameters
None
Return value
Returns true if the device is a smart phone. Otherwise returns false.
removeFieldLabel()
Purpose
Removes the specified field label from the current View or Edit page. This is useful for cases where the field
label takes up extra space and/or is not necessary, such as when displaying an image.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1143
Chapter 15: Reference
Note:
This method applies to the new UI, not the classic UI. Most Rollbase tenants are using the new UI. However,
tenants on older Private Cloud installations might still be using the classic UI.
This method is not supported in portals.
Syntax
rb.newui.util.removeFieldLabel(fieldName)
Parameters
fieldName
The integration name of the field
Return value
None
Example
The following example removes the field label "photo" from the current View or Edit page.
rb.newui.util.removeFieldLabel("photo");
Properties
The properties described in this section allow you to set certain user interface behaviors. Some of these
properties must be set in a custom sidebar script that executes before the user interface starts. See Executing
a script before the UI starts for details.
Note:
The properties in this section apply to the new UI, not the classic UI. Most Rollbase tenants are using the new
UI. However, tenants on older Private Cloud installations might still be using the classic UI.
These properties are not supported in portals.
Ajax Navigation for pages
Purpose
This property allows you to specify whether Rollbase uses page navigation using AJAX requests. Setting it to
false disables page navigation using AJAX requests. Setting it to true enables page navigation using AJAX
requests. This property applies to all of the actions listed below.
Note:
This property applies to the new UI, not the classic UI. Most Rollbase tenants are using the new UI. However,
tenants on older Private Cloud installations might still be using the classic UI.
This property is not supported in portals.
1144 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Client-side JavaScript
You must set this property's value in a custom sidebar script that executes before the UI starts. See Executing
a script before the UI starts for details.
Rollbase performs AJAX requests instead of full page reloads for the following actions:
• When navigating top level tabs on the application menu bar
• When viewing a record (from a record list page to a record view page)
• When navigating back to the record list view from a record view page
• When viewing the next and previous record from a record view page
• When editing a record (Clicking Edit on a record view page). Note: Save is a full page reload.
Fully qualified name
rb.newui.options.applicationPage.ajaxNavigation
Example
The following example disables page navigation using AJAX requests for an application:
<script id="executeBeforeUIStarts">
if(rbf_isNewUI()){
rb.newui.options.applicationPage.ajaxNavigation = false;
}
</script>
Ajax Navigation for tabs
Purpose
This property allows you to specify whether Rollbase uses AJAX requests to navigate between top-level tabs
and tab sub-menus (generic and object). Setting it to false disables navigation between top-level tabs and
tab sub-menus using AJAX requests. Setting it to true enables navigation between top-level tabs and tab
sub-menus using AJAX requests.
Note:
This property applies to the new UI, not the classic UI. Most Rollbase tenants are using the new UI. However,
tenants on older Private Cloud installations might still be using the classic UI.
This property is not supported in portals.
You must set this property's value in a custom sidebar script that executes before the UI starts. See Executing
a script before the UI starts for details.
Fully qualified name
rb.newui.options.tabMenuLink.ajaxNavigation
Example
The following example disables navigation between top-level tabs using AJAX requests for an application:
<script id="executeBeforeUIStarts">
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1145
Chapter 15: Reference
if(rbf_isNewUI()){
rb.newui.options.tabMenuLink.ajaxNavigation = false;
}
</script>
Controlling Timeout on Tab Ajax Loading
Prior to Rollbase v5.0, the Tab Ajax loading was set with a timeout of 10s. Now, the following changes have
been made:
• The Ajax timeout default value is set to 60s
• Allow changing value via JavaScript override with the following property:
rb.newui.options.tabAjaxLoadTimeout. The property unit is in milliseconds.
Customer can change the timeout value using the following script to a custom sidebar or custom header:
<script>
try {
if (!rbf_isNewUI()) {
throw 'This Script is written for New UI';
}
rb.newui.options.tabAjaxLoadTimeout = 5000;
}
catch (err) {
if (console) {
console.log(err);
}
}
</script>
showAdvancedFilterTypes
Purpose
This property allows you to specify whether to show or hide the advanced filter options component in the filter
interface. Setting it to true shows the component.
Note:
This property applies to the new UI, not the classic UI. Most Rollbase tenants are using the new UI. However,
tenants on older Private Cloud installations might still be using the classic UI.
This property is not supported in portals.
Setting it to false hides the component. The screen below shows the advanced filter option component and
the Boolean operator component in the filter interface:
1146 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Client-side JavaScript
When used in conjunction with showBooleanOperators on page 1148, and both are set to false, the entire row
in which they appear is hidden, saving vertical space on the screen:
Note: You must set this property's value in a custom sidebar script that executes before the UI starts. See
Executing a script before the UI starts for details.
Fully qualified name
rb.newui.options.filters.showAdvancedFilterTypes
Example
The following code hides the advanced filter options component.
<script id="executeBeforeUIStarts">
rb.newui.options.filters.showAdvancedFilterTypes = false;
</script>
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1147
Chapter 15: Reference
showBooleanOperators
Purpose
This property allows you to specify whether to show or hide the Boolean operator component in the filter
interface. Setting it to true shows the component.
Note:
This property applies to the new UI, not the classic UI. Most Rollbase tenants are using the new UI. However,
tenants on older Private Cloud installations might still be using the classic UI.
This property is not supported in portals.
Setting it to false hides the component. The screen below shows the Boolean operator component and the
advanced filter option component in the filter interface:
When used in conjunction with showAdvancedFilterTypes on page 1146, and both are set to false, the entire
row in which they appear is hidden, saving vertical space on the screen:
Note: You must set this property's value in a custom sidebar script that executes before the UI starts. See
Executing a script before the UI starts for details.
1148 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Client-side JavaScript
Fully qualified name
rb.newui.options.filters.showBooleanOperators
Example
The following code hides the Boolean operator component.
<script id="executeBeforeUIStarts">
rb.newui.options.filters.showBooleanOperators = false;
</script>
leftRightSectionPairStartsNewRow
Purpose
For generic pages with two columns, this property allows you to specify whether the sections in the left and
right columns align with each other. If set to true, each left/right pair of sections will align at the top. If set to
false (the default), sections in each column take up the available space after the sections above them. The
example below illustrates how this works on a generic page with two columns and four sections.
Note:
This property applies to the new UI, not the classic UI. Most Rollbase tenants are using the new UI. However,
tenants on older Private Cloud installations might still be using the classic UI.
This property is not supported in portals.
With this property set to true, the sections Report Left and Report Right are aligned at the top:
With this property set to true, the sections Report Left and Report Right maintain their alignment when the
Title Chart Right section is collapsed:
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1149
Chapter 15: Reference
With this property set to false, the sections Report Left and Report Right are positioned with respect to the
chart sections in their columns:
With this property set to false, collapsing the Title Chart Right section causes the Report Right section to
move into the available space:
1150 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Client-side JavaScript
Fully qualified name
rb.newui.options.genericPage.leftRightSectionPairStartsNewRow
Example
The following code sets this property to true. This results in the behavior illustrated in the first two screens
above.
<script>
rb.newui.options.genericPage.leftRightSectionPairStartsNewRow = true;
</script>
onLeavingDirtyPage
Purpose
This property controls whether Rollbase opens a notification when a user tries to navigate away from a form
page (new, edit) which has unsaved changes. The notification gives the user a chance to save the changes.
This property has the value true by default. To disable the notifications, set its value to false. You can set
the value of this property in any script component. This property is only available when using the New UI.
Fully qualified name
rb.newui.options.notify.onLeavingDirtyPage
Example
The following example disables notifications when a user navigates away from a page with unsaved changes:
<script>
try {
if ( window.rb !== undefined && window.rb.newui !== undefined )
{
console.log("*** Executing Custom Sidebar for New UI");
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1151
Chapter 15: Reference
rb.newui.options.notify.onLeavingDirtyPage = false;
}
}
catch (e)
{alert ('Error in custom sidebar code' + e);
}
</script>
recordNavigationAjax
Purpose
This property allows you to specify whether Rollbase uses AJAX requests to navigate between object records
(previous and next). Setting it to false disables navigation between object records using AJAX requests.
Setting it to true enables navigation between object records using AJAX requests.
Note:
This property applies to the new UI, not the classic UI. Most Rollbase tenants are using the new UI. However,
tenants on older Private Cloud installations might still be using the classic UI.
This property is not supported in portals.
You must set this property's value in a custom sidebar script that executes before the UI starts. See Executing
a script before the UI starts for details.
Fully qualified name
rb.newui.options.objectViewPage.recordNavigationAjax
Example
The following example disables navigation between object records using AJAX requests for an application:
<script id="executeBeforeUIStarts">
if(rbf_isNewUI()){
rb.newui.options.objectViewPage.recordNavigationAjax = false;
}
</script>
useResponsiveImage
Purpose
Note: This property is deprecated in Rollbase version 4.2. Responsive images are now enabled by default,
and you can control whether an image is responsive by selecting or deselecting the Responsive field for that
image in the page editor.
This property specifies whether image fields are responsive to different screen sizes. When true (the default),
image fields are responsive. When false, image fields are not responsive. When image fields are responsive,
Rollbase ignores image width and height properties for the field in the page editor.
1152 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Client-side JavaScript
Note: You must set this property's value in a custom sidebar script that executes before the UI starts. See
Executing a script before the UI starts for details.
Fully qualified name
rb.newui.options.useResponsiveImage
Example
The following script turns off responsive images:
<script id="executeBeforeUIStarts">
if(rbf_isNewUI()){
rb.newui.options.useResponsiveImage = false;
}
</script>
Algorithm to adjust tabular report columns
Purpose
This property allows you to set a new algorithm to adjust column width of a tabular report grid. Setting it to
false disables the algorithm. Setting it to true enables the algorithm to adjust column width. By default, this
option is set to true.
Note:
This property applies to the new UI, not the classic UI. Most Rollbase tenants are using the new UI. However,
tenants on older Private Cloud installations might still be using the classic UI.
This property is not supported in portals.
You must set this property's value in a custom sidebar script that executes before the UI starts. See Executing
a script before the UI starts for details.
Fully qualified name
rb.newui.options.listView.runNewAlgoToAdjustReportColumns
Example
The following example disables the algorithm to adjust column width:
<script id="executeBeforeUIStarts">
if(rbf_isNewUI()){
rb.newui.options.listView.runNewAlgoToAdjustReportColumns = false;
}
</script>
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1153
Chapter 15: Reference
Property to run adjust column width alorithm
Purpose
This property allows you to enable the
rb.newui.options.listView.runNewAlgoToAdjustReportColumns property based on the number
of columns the report grid has. If report columns are less than this property value, then the algorithm to adjust
the column width is not run. If the number of columns of the report grid is greater that the value of this property,
the alogorithm to adjust the report column width is run. The default value of this property is 6.
Note:
This property applies to the new UI, not the classic UI. Most Rollbase tenants are using the new UI. However,
tenants on older Private Cloud installations might still be using the classic UI.
This property is not supported in portals.
You must set this property value in a custom sidebar script that executes before the UI starts. See Executing
a script before the UI starts for details.
Fully qualified name
rb.newui.options.listView.minNumberOfColumnsReqToRunAlgo
Example
The following example sets the property value to run the algorithm to adjust column width:
<script id="executeBeforeUIStarts">
if(rbf_isNewUI()){
rb.newui.options.listView.minNumberOfColumnsReqToRunAlgo = 6;
}
</script>
Custom events
The events described below are jQuery custom events. You can handle these events in JavaScript to customize
an application that uses the new UI. Progress recommends using the function addEventListener() on page 1140
to handle custom events. See http://www.w3schools.com/jquery/jquery_events.asp for more information about
jQuery events.
Rollbase supports the following custom events:
• rb.newui.util.customEvents.rbs_pageRender — Raised when the AJAX response has been
received from the server and the content has been rendered in the content element. This will be raised
regardless of whether AJAX navigation is enabled. You can handle this event in a JavaScript event handler
in a script component to customize the content on the page.
Note: With AJAX navigation enabled, use a call to addEventListener() for this event instead of
document.ready. See addEventListener() on page 1140 for an example.
See HTML and Script components on page 185 for more information about script components.
1154 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Client-side JavaScript
• rb.newui.util.customEvents.rbs_recordsSelected — Raised when records are selected from
a record list view
• rb.newui.util.customEvents.rbs_recordSelectionCleared — Raised when selected records
in a record list view are cleared
• rb.newui.util.customEvents.rbs_sectionCollapsed — Raised when an expanded page section
is collapsed, after the collapse is complete
• rb.newui.util.customEvents.rbs_sectionExpanded — Raised when a collapsed page section
is expanded, after the expansion is complete
• rb.newui.util.customEvents.rbs_uiResized — Raised when the layout manager has finished
resizing the screen. You can use a handler for this event to perform post-sizing operations.
• rb.newui.util.customEvents.rbs_tabActivated — Raised when a page tab is activated and is
fully visible on the page
• rb.newui.util.customEvents.rbs_viewSelectorChange — Raised when a user selects a different
view on a record list page
• rb.newui.util.customEvents.rbs_sessionExtended — Raised when a user extends a session
from the notification that session is about to expire
• rb.newui.util.customEvents.rbs_notificationDisplayed — This event is for post processing
after a Growl message is displayed. The following parameters are passed in the data parameter as an
object:
• type — The type of the Growl message
• title — The title of the Growl message
• message — The Growl message
• rb.newui.util.customEvents.rbs_gridControlFieldUpdate — Raised when the user updates
a field in a grid control. This is only available for the revised grid control introduced in Rollbase 4.3. See
GridControl on page 1133 for more information.
• rb.newui.util.customEvents.rbs_gridControlRowCreate — Raised when the user creates a
new record in a grid control. This is only available for the revised grid control introduced in Rollbase 4.3.
See GridControl on page 1133 for more information.
• rb.newui.util.customEvents.rbs_gridControlRowDelete — Raised when the user deletes a
record in a grid control. This is only available for the revised grid control introduced in Rollbase 4.3. See
GridControl on page 1133 for more information.
Note: These custom events are not supported in portals.
The following example illustrates how to add an event listener and handler for this event:
<script>
try{
if(!rbf_isNewUI()) {
throw'This Script is written specific to New UI Context';
}
// { type: type, title: title, message: message }
var onNotificationDisplayed = function(event,data){
if(console){
console.log("**** Processing event rbs_notificationDisplayed ****");
console.log("Type: "+ data.type);
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1155
Chapter 15: Reference
console.log("Title: "+ data.title);
console.log("Message: "+ data.message);
}
};
rb.newui.util.addEventListener(rb.newui.util.customEvents.rbs_notificationDisplayed,
onNotificationDisplayed);}
catch(err) {
if(console) {
console.log(err);
}}
</script>
CustomEvent for Dynamic Filter Rendering
You can delay rendering the filter section when using for the first time. If you have JavaScript to customize
filter component, adapt it to run the code after the filter component is rendered. You need to listen to the custom
event rbs_dynamicFilterRendered and execute your customization code in the callback function as exemplified
below.
<script>
try {
if (!rbf_isNewUI()) {
throw 'This Script is written for New UI';
}
var onFilterRender = function ( event, eventData) {
// Now customize the filter the way you want.
// Event Data: { filterEle: theFilterElement, cellId: theCellId, cellOrgId:
theCellOriginalId }
};
rb.newui.util.addEventListener(rb.newui.util.customEvents.rbs_dynamicFilterRendered,
onFilterRender);
}
catch (err) {
if (console) {
console.log(err);
}
}
</script>
Code Generator
To access Rollbase APIs from external computer systems, customers often need to write computer code that
uses Object names, Field names, and some other customer-specific parameters. Writing such code can be a
tedious and error-prone task, since it might require many copy-and-paste operations.
To simplify this task, Rollbase provides a Code Generator, available from the Application Setup page. The
Code Generator parses and fetches a text template that uses the metadata tokens described below.
Template Token Description
{!#SYSTEM_NAME} Name of the Rollbase installation
{!#HOST_NAME} Host name used by the Rollbase installation
{!#CURR_CUSTM.name} Customer name
1156 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Code Generator
Template Token Description
{!#CURR_CUSTM.id} Customer ID
{!#CLASS_NAME} Class name (free text input from the Code Generator
page)
{!#OBJ_LOOP_BEGIN} Marks the beginning of a loop through selected
Objects. Text within the loop is replicated for each
selected Object.
{!#OBJ_LOOP_END} Marks the end of an Object loop.
{!#object.name} Integration name of an Object in a loop.
{!#object.display} Display name of an Object in a loop.
{!#FIELD_LOOP_BEGIN} Marks the beginning of loop through fields of the
current Object. Text within the loop is replicated for
each field (excluding read-only fields).
{!#FIELD_LOOP_END} Marks the end of a Fields loop.
{!#field.name} Integration name of a Field in a loop.
{!#field.display} Display name of a Field in a loop.
Using the Code Generator
Follow these steps to use the Code Generator:
1. Provide the Class name to be used as a {!#CLASS_NAME} token in your code.
2. Select the template:
a) PHP client for the Rollbase REST API
b) Java client for the Rollbase REST API
c) JavaScript (Node.js) client for the Rollbase REST API
d) Custom template (upload)
3. Select Objects to be used in the generated code.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1157
Chapter 15: Reference
4. Click Generate to download the resulting client code.
Metadata API and XML Reference
The SOAP and REST methods in this section provide a way to manipulate the following Rollbase metadata
elements: application, object, field, and relationship definitions. These calls either generate output in XML
format or take input in XML format. The XML schema for these APIs is available at
https://www.rollbase.com/webapi/wsdl/metadata.xsd
Metadata XML reference
The XML definition of a Rollbase application includes the application element and object, field, and relationship
nodes as described in the following topics:
• Application XML Elements on page 1158
• Object XML Definition on page 1161
• Field XML Definition on page 1166
• Relationship XML Definition on page 1172
Application XML Elements
The following sections describe the application-level XML elements that define application metadata:
1158 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Metadata API and XML Reference
• Application Node on page 1159
• ApplicationProps Node on page 1159
• Application Definition XML Example on page 1161
Application Node
Element Name XML Element Type Data Type Description
DisplayName Node String The application display
name.
Description Node String The application
description.
Props Node Complex The application properties.
See the description for
ApplicationProps.
DependentDefs Node String A set of comma-separated
objects, which must be
installed prior to installing
this application.
DataObjectDefs Node Complex A set of object definitions.
See the description for
DataObjectDef.
id Attr int The application ID.
origId Attr int The original application ID.
orderNo Attr int The order in which this
application appears in the
list of applications.
isSystem Attr Boolean Specifies whether this is a
system application.
version Attr int The application version.
terminateOnError Attr Boolean Specifies whether to
terminate the application
when an error occurs.
ApplicationProps Node
The following elements exist in the ApplicationProps element, a child of the Application node.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1159
Chapter 15: Reference
Element Name XML Element Type Data Type Description
pubManaged Node int One of the following
values: 0: unlocked (not
managed), 1: fully locked,
2: partially locked
isDeployed Node boolean If true, application is
deployed and
non-administrative users
who have the appropriate
permissions will be able to
use the application. If
false, only administrators
will have access.
helpField Node Boolean Specifies whether to
enable help pop-ups for
object fields in this
application.
isDeployed Node boolean If true, application is
deployed and
non-administrative users
who have the appropriate
permissions will be able to
use the application. If
false, only administrators
will have access.
dependentDefs Node String Comma-separated,
installer-generated list of
dependent objects.
isHidden Node Boolean Specifies whether this
application is hidden and
does not appear in the
drop-down list of
applications.
useLegacyHeaderFooter Node Boolean Specifies whether to use
the legacy header and
footer in the UI.
showMenus Node Boolean Specifies whether to show
second-level menus in a
row underneath
application tabs.
isMobile Node Boolean Specifies whether to
enable Mobile-Web
functionality for this
application.
1160 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Metadata API and XML Reference
Application Definition XML Example
The following shows an XML example of an Application node:
<Application id="7558" origId="7558" orderNo="3" isSystem="false" version="1" >
<DisplayName>ABC</DisplayName>
<Props>
<pubManaged>0</pubManaged>
<helpField>false</helpField>
<isDeployed>true</isDeployed>
<dependentDefs>,</dependentDefs>
<isHidden>false</isHidden>
<useLegacyHeaderFooter>false</useLegacyHeaderFooter>
<showMenus>false</showMenus>
</Props>
<DependentDefs>USER</DependentDefs>
<DataObjectDefs>
<!-- List of Objects -->
</DataObjectDefs>
</Application>
Object XML Definition
The following nodes and elements describe an object definition:
• DataObjectDef Node on page 1161
• ObjectProps Node on page 1163
• Object Definition XML Example on page 1165
DataObjectDef Node
The following table describes the DataObjectDef XML node.
Element Name XML Element Type Data Type Description
SingularName Node String The singular name for the
object.
PluralName Node String The plural name for the
object.
NameTemplate Node String The template to use when
creating names for new
objects of this type.
Description Node String Description of this object.
Attributes Node String A comma-separated list of
object attributes. See the
Field Groups XML file for
attribute names in System
Console > System >
Control Panel >
Configuration > Field
Groups.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1161
Chapter 15: Reference
Element Name XML Element Type Data Type Description
Props Node Complex A set of properties for this
object. See the
ObjectProps node
description.
DataFieldDefs Node Complex A set of fields for this
object. See the
DataFieldDef node
description.
RelationshipDefs Node Complex A set of relationships for
this object. See the
RelationshipDef node
description.
id Attr int The object ID.
origId Attr int The original ID of the
object.
objDefName Attr String The object integration
name (required).
isSystem Attr Boolean Specifies whether this is a
system object.
isAuditable Attr Boolean Specifies whether audit is
enabled for this object.
isViewable Attr Boolean Specifies whether to track
record views per user.
isFlaggable Attr Boolean Specifies whether to track
record flagging per user.
isDependent Attr Boolean Specifies whether the
object is a dependent
object.
isDeployed Attr Boolean Specifies whether the
object is deployed.
addComponents Attr Boolean Specifies whether the
default components, such
as pages and views will be
added to new the object.
1162 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Metadata API and XML Reference
Element Name XML Element Type Data Type Description
createTab Attr Boolean Specifies whether a tab
will be created for a new
object.
attachApp Attr int OriginalID of application to
which the new object and
tab will be attached.
ObjectProps Node
The elements in the following table are children of the ObjectProps node.
Element Name XML Element Type Data Type Description
auditView Node Boolean Specifies whether to allow
viewing of audit records.
auditCreate Node Boolean Specifies whether to allow
creation of audit records.
auditEdit Node Boolean Specifies whether to allow
edit of audit records.
auditDelete Node Boolean Specifies whether to allow
deletion of audit records.
dataSetName Node String For OpenEdge objects, the
data set name.
defProcess Node int Specifies the ID of the
default workflow process.
deleteFormula Node String Specifies a formula to
calculate delete
permissions for this
record.
editFormula Node String Specifies a formula to
calculate edit permissions
for this record.
enableReports Node Boolean Specifies whether to
enable reports for this
object.
googleSynch Node Boolean For objects with an Event
attribute, specifies whether
to synchronize with the
Google calendar.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1163
Chapter 15: Reference
Element Name XML Element Type Data Type Description
isCloud Node Boolean Specifies whether the
object is an external object
accessed through
DataDirect Cloud.
isLegacy Node Boolean Specifies whether this is
an external object.
isManaged Node Boolean Specifies whether this
object is managed by the
application publisher and
cannot be modified.
isOpenEdge Node Boolean Specifies whether the
object is an OpenEdge
ABL object.
isReadOnly Node Boolean For external objects,
specifies whether the
object is read-only.
loginName Node String Login name for OpenEdge
and external objects that
will be accessed through
DataDirect Cloud.
pkColumn Node String Primary key(s) for
OpenEdge and external
objects.
queryInsert Node String A Base-64 encoded
INSERT query for external
objects.
queryDelete Node String A Base-64 encoded
DELETE query for external
objects.
queryNewID Node String A Base-64 encoded query
to fetch a new record ID
external objects.
querySelect Node String A Base-64 encoded
SELECT query for external
objects.
queryUpdate Node String A Base-64 encoded
UPDATE query for
external objects.
1164 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Metadata API and XML Reference
Element Name XML Element Type Data Type Description
password Node String The password for
OpenEdge objects. This
property is encrypted and
cannot be set with an API
call.
requireUserCreds Node Boolean Specifies whether to
require individual user
credentials for OpenEdge
objects.
resourceURI Node String The URI to an OpenEdge
resource.
showTags Node Boolean Specifies whether to show
Search Tag options.
Object Definition XML Example
The following shows an example DataObjectDef node:
<DataObjectDef id="10359" origId="14184" objDefName="b" isSystem="no" isAuditable="no"
isViewable="no" isFlaggable="no" isDependent="no" isDeployed="yes">
<Props>
<isManaged>false</isManaged>
<defProcess>-1</defProcess>
<enableReports>true</enableReports>
<googMap>false</googMap>
<auditView>false</auditView>
<showTags>false</showTags>
<googSynch>false</googSynch>
</Props>
<SingularName>B</SingularName>
<PluralName>Bs</PluralName>
<DataFieldDefs>
<DataFieldDef id="19869" origId="19869" objName="b" fieldName="sumbur"
dataName="FieldDummy"
uiClass="FormulaField" isRequired="no" isReadOnly="yes" isTextIndexable="no"
isSystem="no"
isAuditable="no" maxLength="0">
<DisplayLabel>Sumbur</DisplayLabel>
<Props>
<returnType>1</returnType>
<decimalPlaces>0</decimalPlaces>
<hideLabel>false</hideLabel>
<formatIndex>0</formatIndex>
<formulaB64>eyFpZH0rMg==</formulaB64>
</Props>
</DataFieldDef>
<!-— More fields here -->
</DataFieldDefs>
<RelationshipDefs>
<RelationshipDef id="19891" origId="19891" relName="R19877" objDef1="b" objDef2="a1"
singularName1="B" pluralName1="Bs" singularName2="A" pluralName2="As" isMultiple1="yes"
isMultiple2="yes" orphanControl1="no" orphanControl2="no" cloneRelated1="no"
cloneRelated2="no" isSystem="no" isPkFk="no">
</RelationshipDef></RelationshipDefs>
</DataObjectDef>
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1165
Chapter 15: Reference
Field XML Definition
The following topics describe the XML elements that describe a field:
• DataFieldDef Node on page 1166
• Field Props Node on page 1168
• Field Definition Example on page 1171
• List Item Node on page 1172
• List XML example on page 1172
DataFieldDef Node
Element Name XML Element Type Data Type Description
DisplayLabel Node String The display label for this
field.
Description Node String Description of this field.
Props Node Complex A set of field properties.
See Field Props Node on
page 1168 for more
information.
ValidationScript Node String A Base-64 encoded
formula to validate this
field.
ListItems Node Complex For SelectList and
similar fields, a set of
picklist items.
imageData Node String For SharedImage fields
only, specifies a Base-64
encoded image.
id Attr int The ID for this field.
origID Attr int The original ID of this field.
objDefName Attr String The integration name of
the object that contains
this field.
columnName Attr String For external objects only,
the database column
name. This value is
required.
1166 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Metadata API and XML Reference
Element Name XML Element Type Data Type Description
fieldName Attr String The integration name of
this field. This value is
required and must be
unique per object.
groupName Attr String The group name for this
field.
dataName Attr String Name of the data type,
which is ignored for new
fields.
uiClass Attr String Specifies the UI type for
this field. Required value,
one of: TextInput,
TextArea, DateInput,
DateTimeInput,
IntInput,
CurrencyInput,
DecimalInput,
CheckBox, URLInput,
EmailInput,
PhoneInput,
SelectList,
SelectListMultiple,
RadioButtons,
CheckBoxesGroup,
AutoNumber,
FileInput,
ImageInput,
SharedImage,
FormulaField,
ExpressionField,
IntegrationLink,
TemplateField.
isRequired Attr Boolean Specifies whether a value
must be entered for this
field on all pages.
isReadOnly Attr Boolean Specifies whether the field
is read-only on all pages
in which it appears.
isTextIndexable Attr Boolean Specifies whether this field
will be indexed for full-text
search.
isAuditable Attr Boolean Specifies whether audit
changes will be tracked for
this field.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1167
Chapter 15: Reference
Element Name XML Element Type Data Type Description
maxLength Attr Int Specifies the maximum
number of characters
allowed as input for
text-based fields
addToPages Attr Boolean Specifies whether an API
call to add a field definition
should also add the newly
created field to object
pages.
Field Props Node
The following table describes elements of a FieldProps node:
Element Name XML Element Type Data Type Description
autoNumFormat Node String For AutoNum fields, the
format. For example, PO#
{YYYY}-{0000000} will
be converted to a value
such as PO#
2007-0000001
startingAutoNumber Node String For AutoNum fields, the
number is used to initialize
the current number.
cols Node Int For TextArea fields, the
number of columns.
decimalPlaces Node Int For DecimalInput fields,
the number of decimal
places.
defValue Node String Specifies a default value
to be displayed for this
field when new records are
created.
fileMaxSize Node Int For FileInput fields,
specifies the maximum
size, in kilobytes, for
uploaded files.
formatIndex Node Int For CurrencyInput
fields, specifies a currency
format index.
formula Node String For formula fields,
specifies a Base-64
encoded formula.
1168 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Metadata API and XML Reference
Element Name XML Element Type Data Type Description
hideLabel Node Boolean Specifies whether to hide
the field display label on
user interface pages.
inputMask Node String For TextInputfields,
specifies an input mask.
inlineEdit Node Boolean Specifies whether this field
can be edited on object
view and edit pages.
isLocalized Node Boolean For text fields, specifies
whether to support input in
a different language.
isShared Node Boolean For SelectInput fields,
specifies whether the
values can be shared with
other fields that provide
multiple choices.
isUnique Node Boolean Specifies whether this field
allows the same value in
more than one record: a
value of true, means
duplicates will not be
allowed.
isWarning Node Boolean Specifies whether
validation errors should be
considered as warnings,
which can be ignored by
the user.
isvShare Node Boolean For fields in an ISV
account on the Master
Server, specifies whether
this field can be viewed
and updated, if applicable,
by ISV tenants.
linkTempl Node String For IntegrationLink
fields, a Base-64 encoded
template for the integration
link.
lowerLabel Node String For CheckBox fields,
specifies an additional
label to render on the right
side of the checkbox.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1169
Chapter 15: Reference
Element Name XML Element Type Data Type Description
maxValue Node Int For numeric fields, the
maximum value allowed.
minValue Node Int For numeric fields, the
minimum value allowed.
publicAccess Node Boolean For FileInput and
ImageInput fields,
specifies whether to allow
public access to uploaded
resource without checking
permissions.
returnType Node Int For FormulaField fields,
specifies the return type.
Available values are:
• decimal number
• currency
• integer
• string
• boolean
• date
• date/time (adjusted to
user's time zone)
• date/time (not adjusted
to user's time zone)
.
rows Node Int For TextArea fields, the
number of rows.
separator Node String For DecimalInput fields,
use this as a separator.
shiftCurrDate Node Int For DateInput fields, add
this number of days to the
current date.
size Node Int Specifies the size in
number of characters for
an HTML input box
sortABC Node Boolean For fields that allow
selections, such as
SelectList, specifies
whether to sort picklist
values in alphabetic order.
1170 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Metadata API and XML Reference
Element Name XML Element Type Data Type Description
source Node String For fields that allow
selections, such as
SelectList, specifies
the source name for
picklist values.
template Node String For TemplateField
fields, specifies a Base-64
encoded template.
useCurrDate Node Boolean For DateInput fields,
specifies whether to use
the current date as the
default value.
useFullDate Node Boolean For DateInput fields,
specifies whether to use
the full text of the date on
view pages.
useRichEditor Node Boolean For TextArea fields,
specifies whether a Rich
Text Editor will be
available to enter text.
valFalse Node String Clears the value for TRUE
(CheckBox fields, External
Objects)
valTrue Node String Sets the value to TRUE
(CheckBox fields, External
Objects)
vertical Node Boolean For fields that have
multiple lines, such as
checkboxes and radio
buttons: if true, align
controls vertically; if false,
align horizontally.
viewWidth Node String The width for this field in a
view, in pixels or %.
Field Definition Example
The following example shows how to use a DataFieldDef node to specify a field definition.
<DataFieldDef objDefName="a1" columnName="STR0" fieldName="my_text2"
dataName="FieldString" uiClass="TextInput" isRequired="yes" isReadOnly="no"
isTextIndexable="yes" isSystem="no" isAuditable="yes" maxLength="0">
<DisplayLabel>My Text</DisplayLabel>
<Props>
<isLocalized>false</isLocalized>
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1171
Chapter 15: Reference
<isUnique>true</isUnique>
</Props>
</DataFieldDef>
List Item Node
Element Name XML Element Type Data Type Description
id Attr int The item ID.
origId Attr int The original ID of the list
item.
orderNo Attr int Required sequential order
in the list for this item.
source Attr String Required name to
distinguish this group of
items.
name Attr String Specifies the display name
for this list (required).
code Attr String Specifies the integration
code for this list.
mainItemId Attr int For dependent picklists,
specifies the ID of the
main item.
isDefault Attr Boolean Specifies whether this list
item is the default for new
records.
List XML example
The following example shows a ListItem node.
<ListItem id="20535" origId="20535" orderNo="5" source="20529"
name="ZZZ" code="z" mainItemId="-1" isDefault="no"/>
Relationship XML Definition
A relationship specifies the cardinality and behavior of two associated objects in a direction. The source of the
relationship, such as invoice, is object 1 and the associated objects, such as line item, is object
two. A corresponding relationship in the other direction would be defined with line item as object 1 and
invoice as object 2. The following topics describe the XML elements that define a relationship:
• RelationshipDef Node on page 1173
• Example of a relationship definition on page 1175
1172 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Metadata API and XML Reference
RelationshipDef Node
The following table describes the child elements of a RelationshipDef node:
Element Name XML Element Type Data Type Description
id Attr int The relationship ID.
origId Attr int The original ID of the
relationship
relName Attr String The required integration
name for this relationship.
objDef1 Attr String A required value that
specifies the integration
name of the first object.
objDef2 Attr String A required value that
specifies the integration
name of the second
object.
singularName1 Attr String A required value that
specifies the singular
name for the first object.
singularName2 Attr String A required value that
specifies the singular
name for the second
object.
pluralName1 Attr String A required value that
specifies the plural name
for the first object.
pluralName2 Attr String A required value that
specifies the plural name
for the second object.
fkobjDef Attr String For external relationships,
specifies the integration
name of the foreign key
object.
pkColumn Attr String For external relationships,
specifies the name of the
database column that
contains the Primary Key.
fkColumn Attr String For external relationships,
specifies name of the
database column that
contains the Foreign Key.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1173
Chapter 15: Reference
Element Name XML Element Type Data Type Description
isMultiple1 Attr Boolean Specifies whether to allow
multiple related records for
the first object (Many to N).
isMultiple2 Attr Boolean Specifies whether to allow
multiple related records for
the second object (N to
Many).
orphanControl1 Attr Boolean Specifies whether to
control orphan records for
the first object. For
example, with a
relationship between obj1
and obj2, setting this
element to True will delete
obj1 records when the
related obj2 record is
deleted.
orphanControl2 Attr Boolean Specifies whether to
control orphan records for
the second object. For
example, with a
relationship between obj1
and obj2, setting this
element to True will delete
obj2 records when the
related obj1 record is
deleted.
cloneRelated1 Attr Boolean Specifies whether to clone
related records for the first
object.
cloneRelated2 Attr Boolean Specifies whether to clone
related records for the
second object.
isSystem Attr Boolean Specifies whether this
relationship is a system
relationship.
1174 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Metadata API and XML Reference
Element Name XML Element Type Data Type Description
isPkFk Attr Boolean For external objects,
specifies whether this is a
primary key-foreign key
relationship.
addToPages Attr Boolean Specifies whether a
relationship created by an
API call should be added
in a new lookup field on
user interface pages.
Example of a relationship definition
The following example shows a RelationshipDef node:
<RelationshipDef id="19877" origId="19877" relName="R19877" objDef1="b" objDef2="a1"
singularName1="B" pluralName1="Bs" singularName2="A" pluralName2="As" isMultiple1="yes"
isMultiple2="yes" orphanControl1="no" orphanControl2="no" cloneRelated1="no"
cloneRelated2="no" isSystem="no" isPkFk="no">
</RelationshipDef>
SOAP Metadata Methods
This section describes the SOAP metadata methods. All metadata methods require the logged-in user to have
administrative privileges, regardless of the view, edit, create and delete permissions set on the application or
object.
createApplicationDef()
Purpose
Creates a new application definition and its components from an XML document. This method will create any
objects described in the document, create their corresponding tabs and menus, and attach both objects and
menus to the newly created application.
See Application XML Elements on page 1158 for a description of the Application XML node and an example
of its use.
Syntax
createApplicationDef(string sessionId, string xmlString);
Parameters
sessionId
A string containing the session ID obtained at log in.
XMLString
A string containing an XML application node description that includes any objects to be created.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1175
Chapter 15: Reference
Output
Status text:
Application ABC has been created
Permissions Required
All metadata methods require administrative privileges, regardless of the view, edit, create and delete permissions
set on the application or object. Establish the session by logging in with credentials for an administrative user.
Example
The following example passes in the XML required to create an application.
String infoMessage = binding.createApplicationDef(sessionId, xmlString);
createObjectDef()
Purpose
Creates a new object definition and its components from an XML document.
See Object XML Definition on page 1161 for a description of the DataObjectDef XML node and an example
of its use.
Syntax
createObjectDef(string sessionId, string xmlString)
Parameters
sessionId
A string containing the session ID obtained at log in.
xmlString
An XML string describing the object in an DataObjectDef node, along with fields and relationships.
Output
Status text: Object ABC has been created
Permissions Required
All metadata methods require administrative privileges, regardless of the view, edit, create and delete permissions
set on the application or object. Establish the session by logging in with credentials for an administrative user.
Example
This example shows how to call createObjectDef():
String infoMessage = binding.createObjectDef(sessionId, xmlString);
1176 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Metadata API and XML Reference
createFieldDef()
Purpose
Creates a new field definition from an XML document.
See Field XML Definition on page 1166 for a description of the DataFieldDef XML node and an example of
its use.
Syntax
createFieldDef(string sessionId, string xmlString)
Parameters
sessionId
A string containing the session ID obtained at log in.
xmlString
An XML string describing the field in an DataFieldDef node.
Output
Status text: Field ABC has been created
Permissions Required
All metadata methods require administrative privileges, regardless of the view, edit, create and delete permissions
set on the application or object. Establish the session by logging in with credentials for an administrative user.
Example
This example shows how to call createFieldDef():
String infoMessage = binding.createFieldDef(sessionId, xmlString);
createRelationshipDef()
Purpose
Creates a new relationship definition from an XML document.
See Relationship XML Definition on page 1172 for a description of the RelationshipDef XML node and an
example of its use.
Syntax
createRelationshipDef(string sessionId, string xmlString);
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1177
Chapter 15: Reference
Parameters
sessionId
A string containing the session ID obtained at log in.
xmlString
An XML string describing the field in an RelationshipDef node.
Output
Status text: Relationship R123456 has been created
Permissions Required
All metadata methods require administrative privileges, regardless of the view, edit, create and delete permissions
set on the application or object. Establish the session by logging in with credentials for an administrative user.
Example
The following example creates a relationship definition:
String infoMessage = binding.createRelationshipDef(sessionId, xmlString);
deleteApplicationDef()
Purpose
Permanently deletes an existing application and its components, including objects that are only assigned to
this application and all corresponding records.
See Application XML Elements on page 1158 for a description of the Application XML node and an example
of its use.
Syntax
deleteApplicationDef(string sessionId, string appId);
Parameters
sessionId
A string containing the session ID obtained at log in.
appId
The original ID of the application to retrieve.
1178 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Metadata API and XML Reference
Output
Status text:
Application ABC has been deleted
Permissions Required
All metadata methods require administrative privileges, regardless of the view, edit, create and delete permissions
set on the application or object. Establish the session by logging in with credentials for an administrative user.
Example
The following example deletes an application.
String infoMessage =
binding.deleteApplicationDef("7ae747a0e36648ef8bd016eec1502779@46216462", "7678");
deleteFieldDef()
Purpose
Permanently deletes an existing field definition from the specified object, along with any existing values for that
field.
See Field XML Definition on page 1166 for a description of the DataFieldDef XML node and an example of
its use.
Syntax
deleteFieldDef(string sessionId, string objDefName, string fieldName);
Parameters
sessionId
A string containing the session ID obtained at log in.
objDefName
String containing the integration name for the object containing the field
fieldName
String containing the integration name for the field definition to delete
Output
Status text: Field ABC has been deleted
Permissions Required
All metadata methods require administrative privileges, regardless of the view, edit, create and delete permissions
set on the application or object. Establish the session by logging in with credentials for an administrative user.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1179
Chapter 15: Reference
Example
The following example deletes the firstName field from lead objects:
String infoMessage = binding.deleteFieldDef(sessionId, "lead", "firstName");
deleteObjectDef()
Purpose
Permanently deletes an existing object definition, its components, and its records.
See Object XML Definition on page 1161 for a description of the DataObjectDef XML node and an example
of its use.
Syntax
deleteObjectDef(string sessionId, string objDefName);
Parameters
sessionId
A string containing the session ID obtained at log in.
objDefName
String containing the integration name for the object definition to delete
Output
Status text: Object ABC has been deleted
Permissions Required
All metadata methods require administrative privileges, regardless of the view, edit, create and delete permissions
set on the application or object. Establish the session by logging in with credentials for an administrative user.
Example
The following example deletes the definition of a lead object, its records, and components.
String infoMessage = binding.deleteObjectDef(sessionId, "lead");
deleteRelationshipDef()
Purpose
Permanently deletes an existing relationship definition.
See Field XML Definition on page 1166 for a description of the RelationshipDef XML node and an example
of its use.
1180 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Metadata API and XML Reference
Syntax
deleteObjectDef(string sessionId, string relName);
Parameters
sessionId
A string containing the session ID obtained at log in.
relName
String containing the integration name for the relationship definition to delete
Output
Status text: Field R123456 has been deleted
Permissions Required
All metadata methods require administrative privileges, regardless of the view, edit, create and delete permissions
set on the application or object. Establish the session by logging in with credentials for an administrative user.
Example
The following example deletes a relationship definition:
String infoMessage = binding.deleteRelationshipDef(sessionId, "R123456");
getApplicationDef()
Purpose
Retrieves a full description of a Rollbase application definition as an XML document. The XML schema for this
document can be found at: https://www.rollbase.com/webapi/wsdl/metadata.xsd
See Application XML Elements on page 1158 for a description of the Application XML node and an example
of its use.
Syntax
getApplicationDef(string sessionId, string appId);
Parameters
sessionId
A string containing the session ID obtained at log in.
appId
The original ID of the application to retrieve.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1181
Chapter 15: Reference
Output
XML document with the application definition in an Application node.
Permissions Required
All metadata methods require administrative privileges, regardless of the view, edit, create and delete permissions
set on the application or object. Establish the session by logging in with credentials for an administrative user.
Example
The following example retrieves an XML description of an application.
String xmlData =
binding.getApplicationDef("7ae747a0e36648ef8bd016eec1502779@46216462","7567");
getFieldDef()
Purpose
Retrieves a description of a field definition as an XML document in a sub-node of the DataObjectDef node.
See Field XML Definition on page 1166 for a description of the DataFieldDef XML node and an example of
its use.
Syntax
getFieldDef(string sessionId, string objDefName, string fieldDefName);
Parameters
sessionId
A string containing the session ID obtained at log in.
objDefName
String containing the integration name of the object definition that contains the field
fieldDefName
String containing the integration name of the field definition to retrieve
Output
An XML document with the field definition in a DataFieldDef node.
Permissions Required
All metadata methods require administrative privileges, regardless of the view, edit, create and delete permissions
set on the application or object. Establish the session by logging in with credentials for an administrative user.
1182 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Metadata API and XML Reference
Example
The following example retrieves the field definition of firstName:
String xmlData = binding.getFieldDef(sessionId, "lead", "firstName");
getObjectDef()
Purpose
Retrieves a full description of an object definition as an XML document. The XML schema for this document
can be found at: https://www.rollbase.com/webapi/wsdl/metadata.xsd
See Object XML Definition on page 1161 for a description of the DataObjectDef XML node and an example
of its use.
Syntax
getObjectDef(string sessionId, string objDefName);
Parameters
sessionId
A string containing the session ID obtained at log in.
objDefName
String containing the integration name for the object definition to retrieve
Output
An XML document containing the object definition description in a DataObjectDef node.
Permissions Required
All metadata methods require administrative privileges, regardless of the view, edit, create and delete permissions
set on the application or object. Establish the session by logging in with credentials for an administrative user.
Example
The following example retrieves the definition of a lead object.
String xmlData = binding.getObjectDef(sessionId, "lead");
getObjectDefNames()
Purpose
Retrieves an array of object definition integration names.
Syntax
getObjectDefNames(string sessionId);
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1183
Chapter 15: Reference
Parameters
sessionId
A string containing the session ID obtained at log in.
Output
Array of object definition integration names
Example
StringArr arr = binding.getObjectDefNames(sessionId);
getRelationshipDef()
Purpose
Retrieves a description of a relationship definition as an XML document in a sub-node of the DataObjectDef
node.
See Relationship XML Definition on page 1172 for a description of the RelationshipDef XML node and an
example of its use.
Syntax
getRelationshipDef(string sessionId, string relName);
Parameters
sessionId
A string containing the session ID obtained at log in.
relName
String containing the integration name of the relationship definition to retrieve
Output
An XML document with the relationship definition in a RelationshipDef node.
Permissions Required
All metadata methods require administrative privileges, regardless of the view, edit, create and delete permissions
set on the application or object. Establish the session by logging in with credentials for an administrative user.
Example
The following example retrieves a relationship definition:
String xmlData = binding.getRelationshipDef(sessionId, "R123456");
1184 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Metadata API and XML Reference
metadataSearch()
Purpose
Searches for a string in metadata and returns results in XML format.
Syntax
metadataSearch(string sessionId, String query);
Parameters
sessionId
A string containing the session ID obtained at log in.
query
The string to search.
Output
An XML document with nodes for each metadata entity found for the search string.
Permissions Required
All metadata methods require administrative privileges, regardless of the view, edit, create and delete permissions
set on the application or object. Establish the session by logging in with credentials for an administrative user.
Example
String xmlResults = binding. metadataSearch(sessionId, "test");
updateApplicationDef()
Purpose
Updates an existing application definition and its components from an XML document. The XML document
must include a valid original ID attribute of the root XML node.
See Application XML Elements on page 1158 for a description of the Application XML node and an example
of its use.
Syntax
updateApplicationDef(string sessionId, string xmlString);
Parameters
sessionId
A string containing the session ID obtained at log in.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1185
Chapter 15: Reference
xmlString
XML description of the application in an Application node, including the objects to be updated
Output
Status text:
Application ABC has been updated
Permissions Required
All metadata methods require administrative privileges, regardless of the view, edit, create and delete permissions
set on the application or object. Establish the session by logging in with credentials for an administrative user.
Example
The following example shows how to invoke updateApplicationDef.
String infoMessage = binding.updateApplicationDef(sessionId, xmlString);
updateFieldDef()
Purpose
Updates an existing field definition from an XML document.
See Field XML Definition on page 1166 for a description of the DataFieldDef XML node and an example of
its use.
Syntax
updateFieldDef(string sessionId, string xmlString);
Parameters
sessionId
A string containing the session ID obtained at log in.
xmlString
An XML string describing the field in an DataFieldDef node.
Output
Status text: Field ABC has been updated
Permissions Required
All metadata methods require administrative privileges, regardless of the view, edit, create and delete permissions
set on the application or object. Establish the session by logging in with credentials for an administrative user.
1186 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Metadata API and XML Reference
Example
The following example shows how to invoke updateFieldDef():
String infoMessage = binding.updateFieldDef(sessionId, xmlString);
updateObjectDef()
Purpose
Updates an existing object definition and its components from an XML document.
See Object XML Definition on page 1161 for a description of the DataObjectDef XML node and an example
of its use.
Syntax
updateObjectDef(string sessionId, string xmlString);
Parameters
sessionId
A string containing the session ID obtained at log in.
xmlString
An XML string describing the object in an DataObjectDef node, along with fields and relationships.
Output
Status text: Object ABC has been updated
Permissions Required
All metadata methods require administrative privileges, regardless of the view, edit, create and delete permissions
set on the application or object. Establish the session by logging in with credentials for an administrative user.
Example
The following example invokes updateObjectDef():
String infoMessage = binding.updateObjectDef(sessionId, xmlString);
updateRelationshipDef()
Purpose
Updates an existing relationship definition from an XML document.
See Relationship XML Definition on page 1172 for a description of the RelationshipDef XML node and an
example of its use.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1187
Chapter 15: Reference
Syntax
updateRelationshipDef(string sessionId, string xmlString);
Parameters
sessionId
A string containing the session ID obtained at log in.
xmlString
An XML string describing the field in an RelationshipDef node.
Output
Status text: Relationship R123456 has been updated
Permissions Required
All metadata methods require administrative privileges, regardless of the view, edit, create and delete permissions
set on the application or object. Establish the session by logging in with credentials for an administrative user.
Example
The following example updates a relationship definition:
String infoMessage = binding.updateRelationshipDef(sessionId, xmlString);
REST Metadata Methods
This section describes the REST metadata methods. All metadata methods require the logged-in user to have
administrative privileges, regardless of the view, edit, create and delete permissions set on the application or
object.
createApplicationDef
Purpose
Creates a new application definition and its components from an XML document. This API will create the objects
corresponding tabs and menus, and attach both to the newly created application. See the XML schema for this
document: https://www.rollbase.com/webapi/wsdl/metadata.xsd
See Application XML Elements on page 1158 for a description of the Application XML node and an example
of its use.
HTTP Method
POST
URL
https://www.rollbase.com/rest/api/createApplicationDef
1188 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Metadata API and XML Reference
URL Parameters
sessionId
The session ID obtained from the body of the response when calling login on page 1246.
xmlString
An XML description of the application in an Application node, including the objects to be created.
Permissions Required
Full administrative privileges
Response
Application ABC has been created
createFieldDef
Purpose
Creates a new field definition from an XML document.
See Field XML Definition on page 1166 for a description of the DataFieldDef XML node and an example of
its use.
HTTP Method
POST
URL
https://www.rollbase.com/rest/api/createFieldDef
URL Parameters
sessionId
The session ID obtained from the body of the response when calling login on page 1246.
xmlString
An XML description of the field in a DataFieldDef node.
Permissions Required
Full administrative permissions
Response
Status text: Field ABC has been created
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1189
Chapter 15: Reference
createObjectDef
Purpose
Creates a new object definition and its components from an XML document. See the XML schema for this
document: https://www.rollbase.com/webapi/wsdl/metadata.xsd
See Object XML Definition on page 1161 for a description of the DataObjectDef XML node and an example
of its use.
HTTP Method
POST
URL
https://www.rollbase.com/rest/api/createObjectDef
URL Parameters
sessionId
The session ID obtained from the body of the response when calling login on page 1246.
xmlString
XML description of object in the DataObjectDef node, including the fields, and relationships to be
created.
Permissions Required
Full administrative permissions
Response
"test" object definition has been created. (ID=1953742)
createRelationshipDef
Purpose
Creates a new relationship definition from an XML document.
See Field XML Definition on page 1166 for a description of the RelationshipDef XML node and an example
of its use.
HTTP Method
POST
URL
https://www.rollbase.com/rest/api/createRelationshipDef
1190 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Metadata API and XML Reference
URL Parameters
sessionId
The session ID obtained from the body of the response when calling login on page 1246.
xmlString
An XML description of the relationship in a RelationshipDef node.
Permissions Required
Full administrative permissions
Response
Status text: Relationship R123456 has been created
deleteApplicationDef
Purpose
Permanently deletes an existing application and its components. Any objects assigned to this application, that
are not assigned to other applications, and the corresponding records will also be deleted.
See Application XML Elements on page 1158 for a description of the Application XML node and an example
of its use.
HTTP Method
DELETE or GET
URL
https://www.rollbase.com/rest/api/deleteApplicationDef
URL Parameters
sessionId
The session ID obtained from the body of the response when calling login on page 1246.
appId
The original ID of the application.
Permissions Required
Full administrative privileges
Response
Application ABC has been deleted
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1191
Chapter 15: Reference
deleteFieldDef
Purpose
Deletes a field definition from the specified object.
See Field XML Definition on page 1166 for a description of the DataFieldDef XML node and an example of
its use.
HTTP Method
DELETE or GET
URL
https://www.rollbase.com/rest/api/deleteFieldDef
URL Parameters
sessionId
The session ID obtained from the body of the response when calling login on page 1246.
objName
The object integration name.
fieldName
The field integration name.
Permissions Required
Full administrative permissions
Response
Status Text: Field ABC has been deleted
deleteObjectDef
Purpose
Permanently deletes an existing object definition, its components and its records.
See Object XML Definition on page 1161 for a description of the DataObjectDef XML node and an example
of its use.
HTTP Method
DELETE or GET
URL
https://www.rollbase.com/rest/api/deleteObjectDef
1192 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Metadata API and XML Reference
URL Parameters
sessionId
The session ID obtained from the body of the response when calling login on page 1246.
objName
The object integration name.
Permissions Required
Full administrative permissions
Response
Object ABC has been deleted
deleteRelationshipDef
Purpose
Deletes the relationship definition specified by the integration name.
See Field XML Definition on page 1166 for a description of the RelationshipDef XML node and an example
of its use.
HTTP Method
DELETE or GET
URL
https://www.rollbase.com/rest/api/deleteRelationshipDef
URL Parameters
sessionId
The session ID obtained from the body of the response when calling login on page 1246.
relName
The relationship integration name.
Permissions Required
Full administrative permissions
Response
Status text: Relatinship R123456 has been deleted
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1193
Chapter 15: Reference
getApplicationDef
Purpose
Retrieves the full description of a Rollbase application definition as an XML document. The XML schema for
this document can be found at: https://www.rollbase.com/webapi/wsdl/metadata.xsd
See Application XML Elements on page 1158 for a description of the Application XML node and an example
of its use.
HTTP Method
GET
URL
https://www.rollbase.com/rest/api/getApplicationDef
URL Parameters
sessionId
The session ID obtained from the body of the response when calling login on page 1246.
appId
The original ID of the application.
Required Permissions
One of: VIEW, CREATE, EDIT, DELETE (VIEW by default)
Response
XML document with the application definition description in an Application node.
An application XML generated by this API method will include only the subset of the metadata unlike the
application XML generated from UI. The elements that are exported as part of the getApplicationDef API which
has a relationship are:
• <Application>
• <DisplayName>
• <DependentDefs>
• <DataObjectDefs>
• <DataObjectDef> - <Props>, <SingularName> , <PluralName> , <NameTemplate>,
<DataFieldDefs> - <DataFieldDef>, <DisplayLabel>, <Description>
• <RelationshipDefs> - <RelationshipDef>
The following elements are not exported as a part of the application XML.
• <Attributes> - packedId, language
• <PostInstallScript>
• <PostAppInstallScript>
• <PostAppUpdateScript>
1194 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Metadata API and XML Reference
• <UITemplate>
• <DependentDefs> - not included if there is no relationship
• <DataObjectDefs> - The missing elements are – <ListViews>, <Actions>, <Statuses>,
<Processes>, <Buttons>, <ConversionMaps>, <Charts>, <Gauges>, <Reports>,
<Templates>, <Events>, <Questions>, <MobileCards>, and ‘hasPermissions’ attribute
in <DataFieldDef>
• <Menus>
• <WebPageDefs>
• <Portals>
• <LegacyReports>
• <CustomReports>
• <Roles>
• <HostedFiles>
• <CatalogDefs>
• <BatchJobs>
• <RolePages>
• <SeedRecords>
getFieldDef
Purpose
Retrieves a full description of a field definition as an XML document in the sub-node describing objects.
See Field XML Definition on page 1166 for a description of the DataFieldDef XML node and an example of
its use.
HTTP Method
GET
URL
https://www.rollbase.com/rest/api/getFieldDef
URL Parameters
sessionId
The session ID obtained from the body of the response when calling login on page 1246.
objName
The object integration name.
fieldName
The field integration name.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1195
Chapter 15: Reference
Permissions Required
One of: VIEW, CREATE, EDIT, DELETE (VIEW by default)
Response
An XML document with the field definition in a DataFieldDef node.
getObjectDef
Purpose
Retrieves the full description of an object definition as an XML document. See the XML schema for this document:
https://www.rollbase.com/webapi/wsdl/metadata.xsd
See Object XML Definition on page 1161 for a description of the DataObjectDef XML node and an example
of its use.
HTTP Method
GET
URL
https://www.rollbase.com/rest/api/getObjectDef
URL Parameters
sessionId
The session ID obtained from the body of the response when calling login on page 1246.
objName
The object integration name.
Permissions Required
One of: VIEW, CREATE, EDIT, DELETE (VIEW by default)
Response
An XML document with the object definition description in a DataObjectDef node
getObjectDefNames
Purpose
Retrieves a list of object definition names. Output is limited to objects for which the current user has permissions
to view, create, edit, and delete.
HTTP Method
GET
1196 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Metadata API and XML Reference
URL
https://www.rollbase.com/rest/api/getObjectDefNames
URL Parameters
sessionId
The session ID obtained from the body of the response when calling login on page 1246.
permissions
An optional parameter specifying one of: view, create, edit, or delete
output
Optional parameter specifying the output format, one of: xml (default) or json.
Required Permissions
One of: VIEW, CREATE, EDIT, DELETE (VIEW by default)
Response
Names of object definitions in XML or JSON.
Example
Sample Response:
<?xml version="1.0" encoding="UTF-8"?>
<resp status="ok">
<names>
<name>visitor</name>
<name>process</name>
<name>COMMLOG</name>
</names>
</resp>
getRelationshipDef
Purpose
Retrieves an XML document containing a full description of a relationship definition in a sub-node of the node
describing an object.
See Field XML Definition on page 1166 for a description of the RelationshipDef XML node and an example
of its use.
HTTP Method
GET
URL
https://www.rollbase.com/rest/api/getRelationshipDef
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1197
Chapter 15: Reference
URL Parameters
sessionId
The session ID obtained from the body of the response when calling login on page 1246.
relName
The relationship integration name.
Permissions Required
One of: VIEW, CREATE, EDIT, DELETE (VIEW by default)
Response
An XML document with a relationship definition in the RelationshipDef node.
metadataSearch
Purpose
Searches for a string in metadata and returns results in XML format.
HTTP Method
GET
URL
https://www.rollbase.com/rest/api/metadataSearch
URL Parameters
sessionId
The session ID obtained from the body of the response when calling login on page 1246.
query
A text pattern to search.
Response
An XML document with nodes for each metadata entity found for the search string.
Permissions Required
Full administrative permissions.
Example
Sample XML response:
<resp status="ok">
<SearchResults>
<SearchResult id="376768" name="AJAX API Test" type="Application"
updatedAt="2014-08-22T18:57:41Z" />
1198 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Metadata API and XML Reference
<SearchResult id="376879" name="AJAX Test" type="Page" updatedAt="2014-08-25T21:16:27Z"
/>
<SearchResult id="376881" name="AJAX Test" type="Menu" updatedAt="2014-08-22T18:58:20Z"
/>
<SearchResult id="376825" name="All Tests" type="View" objDefName="test"
updatedAt="2014-08-22T18:57:41Z" />
</SearchResults>
</resp>
updateApplicationDef
Purpose
Updates an existing application definition and its components from an XML document. The XML document
must include a valid Original ID as an attribute to the root XML node for the application to be updated. See the
XML description.
See Application XML Elements on page 1158 for a description of the Application XML node and an example
of its use.
HTTP Method
PUT or POST
URL
https://www.rollbase.com/rest/api/createApplicationDef
URL Parameters
sessionId
The session ID obtained from the body of the response when calling login on page 1246.
xmlString
An XML description of the field in a DataFieldDef node.
Permissions Required
Full administrative permissions
Response
Application ABC has been updated
updateFieldDef
Purpose
Updates an existing field definition from an XML document.
See Field XML Definition on page 1166 for a description of the DataFieldDef XML node and an example of
its use.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1199
Chapter 15: Reference
HTTP Method
PUT or POST
URL
https://www.rollbase.com/rest/api/updateFieldDef
URL Parameters
sessionId
The session ID obtained from the body of the response when calling login on page 1246.
xmlString
An XML description of the field in a DataFieldDef node.
Permissions Required
Full administrative permissions
Response
Status text: Field ABC has been updated
updateObjectDef
Purpose
Updates an existing object definition and its components from an XML document. See the XML schema for
this document: https://www.rollbase.com/webapi/wsdl/metadata.xsd
See Object XML Definition on page 1161 for a description of the DataObjectDef XML node and an example
of its use.
HTTP Method
PUT or POST
URL
https://www.rollbase.com/rest/api/updateObjectDef
URL Parameters
sessionId
The session ID obtained from the body of the response when calling login on page 1246.
xmlString
An XML description of the object in a DataObjectDef node, including fields and relationships.
1200 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Rollbase REST Methods
Permissions Required
Full administrative privileges
Response
Object ABC has been updated
updateRelationshipDef
Purpose
Updates an existing Relationship definition from an XML document.
See Field XML Definition on page 1166 for a description of the RelationshipDef XML node and an example
of its use.
HTTP Method
PUT or POST
URL
https://www.rollbase.com/rest/api/updateRelationshipDef
URL Parameters
sessionId
The session ID obtained from the body of the response when calling login on page 1246.
xmlString
An XML description of the relationship in a RelationshipDef node.
Permissions Required
Full administrative permissions
Response
Status text: Relationship R123456 has been updated
Rollbase REST Methods
The Rollbase REST API uses the same workflow mechanism as the standard Rollbase user interface. For
instance, triggers designed to run on object record creation will run if a record is created through the REST
API.
Each REST method is accessed through URLs of the form:
https://www.rollbase.com/rest/api/{method_name}
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1201
Chapter 15: Reference
Parameters to methods can be supplied as URL parameters for GET calls or in the HTTP request for POST
calls. An XML document or JSON object containing the result of the call or an error message will be returned
as a response.
Example of a GET call:
https://www.rollbase.com/rest/api/logout?sessionId=ba0787e245befcb47@1482&output=xml
A successful response:
<?xml version="1.0" encoding="UTF-8" ?>
<resp status="ok"></resp>
An error response:
<?xml version="1.0" encoding="UTF-8" ?>
<resp status="login">
<err>Session expired or invalid login credentials</err>
</resp>
Most REST methods require the logged-in user to have the appropriate permission for the type of object used
in the method call. For example, calling the the create method to create a Customer record requires the
logged-in user to have Create permission on the Customer object. The documentation for each method includes
the required permissions.
It is a good practice for REST-only clients to use credentials of users with the role Server API. Users with that
role cannot log into Rollbase as regular users.
appXML
Purpose
Returns a Rollbase application as an XML document.
HTTP Method
GET
URL
https://www.rollbase.com/rest/api/appXML
URL Parameters
sessionId
The session ID obtained from the body of the response when calling login on page 1246.
appId
ID of application used to generate XML.
Permissions Required
Full administrative privileges.
Response
Application XML
1202 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Rollbase REST Methods
bulkCreate
Purpose
Creates records from a bulk CSV upload. The output parameter is optional.
In your REST request you must specify a content-type HTTP header with a value text/csv as your request
body contains CSV data. Refer to online resources for more information on HTTP headers.
HTTP Method
POST
URL
https://www.rollbase.com/rest/api/bulkCreate
URL Parameters
sessionId
The session ID obtained from the body of the response when calling login on page 1246.
mapId
The original ID of a previously created Data Import Map.
synch
If true, process the import synchronously and return the IDs of the created records. If false
(default), process the import asynchronously. The user will receive an email with the results of the
import.
importMode
Specifies the import mode. Can be one of the following:
• 0 — Normal; runs all triggers and creates picklist values on the fly if createAction is true.
Best to use with medium-sized uploads.
• 1 — Test; limits upload to five records and displays results including debug information from
triggers. Creates picklist values on the fly if createAction is true. Use to test before loading
a full set of data.
• 2 — Bulk; does not run triggers and does not create picklist values on the fly. Optimized for fast
processing of large imports.
createAction
Boolean that specifies whether to create picklist values on the fly while importing. When true, picklist
values are created. When false, picklist values are not created. The importMode parameter must
be 0 or 1 for picklist values to be created.
output
Optional parameter specifying the output format, one of: xml (default) or json.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1203
Chapter 15: Reference
Permissions Required
Create permission for the requested object type.
Response
Report on created record similar to report after CSV import
bulkCreateOrUpdate
Warning: Support for using this method with external objects (such as those mapped to external tables,
to OpenEdge Service objects, or through a D2C connection) is a beta feature. This method is supported
in production systems, except for external objects.
Purpose
Updates existing records or creates new records from a bulk CSV upload. The output parameter is optional.
In your REST request you must specify a content-type HTTP header with a value text/csv as your request
body contains CSV data. Refer to online resources for more information on HTTP headers.
HTTP Method
POST
URL
https://www.rollbase.com/rest/api/bulkCreateOrUpdate
URL Parameters
sessionId
The session ID obtained from the body of the response when calling login on page 1246.
mapId
The original ID of a previously created Data Import Map.
[fieldId]|[triggerId]
The ID of unique field used to identify records to be updated or the original ID of a Unique Fields
Combination trigger.
synch
If true, process the import synchronously and return the IDs of the created records. If false
(default), process the import asynchronously. The user will receive an email with the results of the
import.
importMode
Specifies the import mode. Can be one of the following:
• 0 — Normal; runs all triggers and creates picklist values on the fly if createAction is true.
Best to use with medium-sized uploads.
1204 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Rollbase REST Methods
• 1 — Test; limits upload to five records and displays results including debug information from
triggers. Creates picklist values on the fly if createAction is true. Use to test before loading
a full set of data.
• 2 — Bulk; does not run triggers and does not create picklist values on the fly. Optimized for fast
processing of large imports.
createAction
Boolean that specifies whether to create picklist values on the fly while importing. When true, picklist
values are created. When false, picklist values are not created. The importMode parameter must
be 0 or 1 for picklist values to be created.
output
Optional parameter specifying the output format, one of: xml (default) or json.
Permissions Required
Edit permission for the object type of each requested record. Create permission for the object type of each
new record.
Response
Report on created/updated record similar to report after CSV import.
bulkDelete
Purpose
Deletes (moves to Recycle Bin) a group of specified records. The output parameter is optional. If you are
deleting more than 1500 records in a single call, use the POST HTTP method.
HTTP Method
POST, DELETE, or GET
URL
https://www.rollbase.com/rest/api/bulkDelete
URL Parameters
sessionId
The session ID obtained from the body of the response when calling login on page 1246.
ids
Comma-separated list of record IDs.
objName
The object integration name.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1205
Chapter 15: Reference
output
Optional parameter specifying the output format, one of: xml (default) or json.
Permissions Required
Delete permission for the requested object type.
Response
Report on deleted record similar to report after CSVdelete.
bulkUpdate
Warning: Support for using this method with external objects (such as those mapped to external tables,
to OpenEdge Service objects, or through a D2C connection) is a beta feature. This method is supported
in production systems, except for external objects.
Purpose
Updates records from a bulk CSV upload. The output parameter is optional.
In your REST request you must specify a content-type HTTP header with a value text/csv as your request
body contains CSV data. Refer to online resources for more information on HTTP headers.
HTTP Method
PUT or POST
URL
https://www.rollbase.com/rest/api/bulkUpdate
URL Parameters
sessionId
The session ID obtained from the body of the response when calling login on page 1246.
mapId
The original ID of a previously created Data Import Map.
[fieldId]|[triggerId]
The ID of unique field used to identify records to be updated or the original ID of a Unique Fields
Combination trigger.
synch
If true, process the import synchronously and return the IDs of the created records. If false
(default), process the import asynchronously. The user will receive an email with the results of the
import.
1206 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Rollbase REST Methods
importMode
Specifies the import mode. Can be one of the following:
• 0 — Normal; runs all triggers and creates picklist values on the fly if createAction is true.
Best to use with medium-sized uploads.
• 1 — Test; limits upload to five records and displays results including debug information from
triggers. Creates picklist values on the fly if createAction is true. Use to test before loading
a full set of data.
• 2 — Bulk; does not run triggers and does not create picklist values on the fly. Optimized for fast
processing of large imports.
createAction
Boolean that specifies whether to create picklist values on the fly while importing. When true, picklist
values are created. When false, picklist values are not created. The importMode parameter must
be 0 or 1 for picklist values to be created.
output
Optional parameter specifying the output format, one of: xml (default) or json.
Permissions Required
Edit permission for the requested object type.
Response
Report on updated record similar to report after CSV update
clearDataObjectCache
Purpose
Clears the cache of object data records on production servers. Progress recommends you use this method
after heavy use of API operations. The output parameter is optional.
HTTP Method
GET
URL
https://www.rollbase.com/rest/api/clearDataObjectCache
URL Parameters
sessionId
The session ID obtained from the body of the response when calling login on page 1246.
output
Optional parameter specifying the output format, one of: xml (default) or json.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1207
Chapter 15: Reference
Permissions Required
Full administrative permissions
Response
Standard success or failure output.
create
Purpose
Creates a new record using data from an XML document. This method can be used to create a single record
or a single record and related records.
Note: Do not use this method with PHP CURL. Instead use create2
HTTP Method
POST
URL
https://www.rollbase.com/rest/api/create
URL Parameters
sessionId
The session ID obtained from the body of the response when calling login on page 1246.
objName
The object integration name.
requestBody
XML document containing object name, "useIds" attribute(true or false - same meaning as in
Web API), and Fields for the new record (see example below).
output
Optional parameter specifying the output format, one of: xml (default) or json.
Permissions Required
Create permission for the requested object type.
Response
The ID and integration name of the new record and a status of ok (see examples below).
1208 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Rollbase REST Methods
Example
Create input example:
<?xml version="1.0" encoding="utf-8" ?>
<data objName="person" useIds="false">
<Field name="club_member">false</Field>
<Field name="lastName">Smith</Field>
<Field name="status">Created</Field>
</data>
Create output example (XML):
<resp status="ok">
<data id="314452" objName="person" />
<Msg>12 fields have been processed.</Msg>
</resp>
Create output example (JSON):
{
id: 314452
objName: "person"
status: "ok"
}
To create related objects in the same call, include a "composite" XML node which wraps a set of "data" XML
nodes as described above. A new record is created for each "data" XML node. These new nodes have
relationships with with core record. Consider this example with dependent nodes:
<?xml version="1.0" encoding="utf-8" ?>
<data objName="person" useIds="false">
<Field name="club_member">false</Field>
<Field name="lastName">Smith</Field>
<Field name="status">Created</Field>
<composite>
<data objName="payment" useIds="false">
<Field name="amount">500.00</Field>
<Field name="paym_date">09/12/2011</Field>
</data>
<data objName="payment" useIds="false">
<Field name="amount">450.00</Field>
<Field name="paym_date">09/22/2011</Field>
</data>
</composite>
</data>
This XML creates one "person" record and two related "payment" records in one call. Output example:
<resp status="ok">
<data id="314452" objName="person" />
<Msg>12 fields have been processed. 2 related records have been created.</Msg>
</resp>
createArr
Purpose
Creates a group of new records using data from an XML document.
HTTP Method
POST
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1209
Chapter 15: Reference
URL
https://www.rollbase.com/rest/api/createArr
URL Parameters
sessionId
The session ID obtained from the body of the response when calling login on page 1246.
output
Optional parameter specifying the output format, one of: xml (default) or json.
Request Body
XML document containing object name, "useIds" attribute(true or false - same meaning as in the
Web API), and Fields for new records wrapped in <data> XML nodes (see example below).
Required Permissions
Create permission for the requested object types.
Response
The ID and integration name of the new record and a status of ok (see examples below).
Example
Input example:
<?xml version="1.0" encoding="utf-8" ?>
<request>
<data objName="person" useIds="false">
<Field name="club_member">false</Field>
<Field name="lastName">Smith</Field>
<Field name="status">Created</Field>
</data>
<data objName="person" useIds="false">
<Field name="club_member">true</Field>
<Field name="lastName">Green</Field>
<Field name="status">Created</Field>
</data>
</request>
Output example (XML):
<resp status="ok">
<data id="314452" objName="person"/>
<data id="314453" objName="person"/>
</resp>
Output example (JSON):
{
"ids": 314452,
"objName": "person",
"status": "ok"
},
{
"ids": 314453,
"objName": "person",
"status": "ok"
1210 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Rollbase REST Methods
createCustomer
Purpose
Creates a new customer record and starts the creation process using data from URL parameters. For private
cloud users, the user credentials for the user sending this request must belong to the Master server. The URL
parameter password can be used to set specific password for first administrative user, otherwise, a temporary
password will be created and sent through email. The output parameter is optional.
HTTP Method
POST
URL
https://www.rollbase.com/rest/api/createCustomer
URL Parameters
sessionId
The session ID obtained from the body of the response when calling login on page 1246.
useIds
Boolean value. If true, use numeric IDs for lookup and picklist values; otherwise use integration
codes and record names.
field1;[field2; ...]
Parameter's name - integration name of field to set; parameter's value - value of field to set. Same
for other fields.
output
Optional parameter specifying the output format, one of: xml (default) or json.
Permissions Required
Create permission for the Customer type.
Response
ID of newly created record as a long wrapped in an XML document or a JSON string (see example below).
Example
Single create input example:
companyName=API+Test&[email protected]&lastName=Admin
&[email protected]&timeZone=PST
&[email protected]&password=my_password
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1211
Chapter 15: Reference
Note: The API call must not have any blank spaces in it.
Output example:
{
id: 7941
objName: "CUSTOMER"
status: "ok"
}
create2
Purpose
Warning: This method is deprecated. Please change any existing code to use createRecord on page
1213, which takes an object ID as a parameter.
Creates a new record using data from URL parameters. The names of the URL parameters used by this API
are field integration names. If a field is not found, the system ignores the URL parameter. Field values must
be formatted the same way as CSV imported values. For more information, see Importing Data.
Note: Use this method with the PHP CURL package.
HTTP Method
POST
URL
https://www.rollbase.com/rest/api/create2
URL Parameters
sessionId
The session ID obtained from the body of the response when calling login on page 1246.
objName
The object integration name.
useIds
true or false.
output
The output format, one of: xml (default), json, or csv.
field1;[field2; ...]
Parameter's name - integration name of field to set; parameter's value - value of field to set.
1212 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Rollbase REST Methods
Permissions Required
Create permission for the requested object type.
Response
The ID and integration name of the new record wrapped in an XML document (see example below).
Example
Input example (URL parameters):
&objDefName=person&useIds=false&club_member=false&lastName=Smith&status=Created
Output example:
<resp status="ok">
<data id="314452" objName="person" />
<Msg>12 fields have been processed</Msg>
</resp>
createRecord
Purpose
Similar to create on page 1208, creates a new record. Returns the ID of the newly created record as a string.
This method works for external objects, including those mapped to OpenEdge service objects.
Provide the integration names of the fields to set along with their values. If a field is not found, the system will
ignore that URL parameter. Field values must be formatted the same way as you would for a CVS import; see
Importing data on page 622.
HTTP Method
POST
URL
https://www.rollbase.com/rest/api/createRecord
URL Parameters
sessionId
The session ID obtained from the body of the response when calling login on page 1246.
objName
The object integration name.
useIds
Boolean value. If true, use numeric IDs for lookup and picklist values; otherwise use integration
codes and record names.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1213
Chapter 15: Reference
field1, field2, ...
Integration name of the field(s) and their values. You must supply a value for required fields. Some
fields, such as those that represent relationships, can have multiple values. Use the field name only
once, and specify the ID of the records to attach separated with a | symbol.
@p1
When creating a User record, the password for the new user. This parameter is optional. If it is not
specified:
• If the password is managed by Rollbase, Rollbase generates a temporary password for the user.
• If the password is not managed by Rollbase (external authentication), the password remains the
same as the one in the external system that manages the password.
@resetPassword
When creating a User record, sets a temporary password for the user. This parameter is optional.
This applies in cases where the user is already present in an external system and Rollbase can set
the password, for example, when the user already has a Progress ID (Hosted Rollbase) or is already
a user in an OpenEdge SPA configuration where set password is configured. If the @p1 parameter
is passed, Rollbase ignores this parameter.
output
Optional parameter specifying the output format, one of: xml (default) or json.
Permissions Required
Create permission for the requested object type.
Response
The ID of the newly created record as a long value and a status of ok, wrapped in an XML document or JSON
string.
Example
Input example (URL parameters):
&objName=USER&useIds=false&firstName=John&lastName=Smith&[email protected]&@p1=mypassword&sendWelcomeEmail=false
Output example (XML):
<resp status="ok">
<data id=”314452” objName=”USER” />
<Msg>4 fields have been processed</Msg>
</resp>
Output example (JSON):
{
id: 314452
objName: "USER"
status: "ok"
}
1214 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Rollbase REST Methods
delete
Purpose
Moves the specified data record to the Recycle Bin. The output parameter is optional.
HTTP Method
DELETE or GET
URL
https://www.rollbase.com/rest/api/delete
URL Parameters
sessionId
The session ID obtained from the body of the response when calling login on page 1246.
id
Record's ID.
output
Optional parameter specifying the output format, one of: xml (default) or json.
Permissions Required
Delete permission for the requested object type.
Response
Standard success or failure output
Example
Output example:
<resp status="ok">
<Msg>Record has been deleted</Msg>
</resp>
deleteArr
Purpose
Moves group of specified data record to the Recycle Bin. The output parameter is optional.
For external objects (such as those mapped to external tables, to OpenEdge Service objects, or through a D2C
connection), you must specify both the objName and id fields.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1215
Chapter 15: Reference
HTTP Method
DELETE or GET
URL
https://www.rollbase.com/rest/api/deleteArr
URL Parameters
sessionId
The session ID obtained from the body of the response when calling login on page 1246.
ids
Comma-separated list of record IDs.
output
Optional parameter specifying the output format, one of: xml (default) or json.
Permissions Required
Delete permission for the requested object type.
Response
Standard success or failure output
Example
Output example:
<resp status="ok">
<Msg>2 records have been deleted.</Msg>
</resp>
deleteRecord
Purpose
Moves Rollbase object records to the Recycle bin. Deletes external objects, including those mapped to OpenEdge
Service objects.
HTTP Method
DELETE or GET
URL
https://www.rollbase.com/rest/api/deleteRecord
1216 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Rollbase REST Methods
URL Parameters
sessionId
The session ID obtained from the body of the response when calling login on page 1246.
objName
The object integration name.
id
The record ID.
output
Optional parameter specifying the output format, one of: xml (default) or json.
Permissions Required
Delete permission for the requested object type.
Response
Standard success or failure output.
Example
Output example in XML format:
<resp status="ok">
<Msg>Record has been deleted.</Msg>
</resp>
getApplicationIds
Purpose
Retrieves Ids of all the applications available for the currently logged user.
HTTP Method
GET
URL
https://www.rollbase.com/rest/api/getApplicationIds
URL Parameters
sessionId
The session ID obtained from the body of the response when calling login on page 1246.
output
Optional parameter specifying the output format, one of: xml (default) or json.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1217
Chapter 15: Reference
Response
Ids of all the applications available for the currently logged user.
Example
Sample Response:
<?xml version="1.0" encoding="UTF-8"?>
<resp status="ok">
<ids>
<id>123456</id>
<id>123490</id>
</ids>
</resp>
getAuthentication
Purpose
Returns the default authentication profile for the tenant. This method is only available for Rollbase Private
Cloud.
HTTP Method
GET
URL
https://www.rollbase.com/rest/api/getAuthentication
URL Parameters
sessionId
The session ID obtained from the body of the response when calling login on page 1246.
output
Optional parameter specifying the output format, one of: xml (default) or json.
Permissions Required
Full administrative privileges.
Response
The authentication for the tenant in XML or JSON format.
Examples
Output example in XML format:
<?xml version="1.0" encoding="UTF-8" ?>
<resp status="ok">
<authType>0</authType>
<authDescription>Password</authDescription>
<APIAuthType>0</APIAuthType>
<authAPIDescription>Password</authAPIDescription>
1218 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Rollbase REST Methods
<useSecQuestions>false</useSecQuestions>
<securityLevel>Low</securityLevel>
<expirPolicy>0</expirPolicy>
<enablePasswordHistory>false</enablePasswordHistory>
<passwordHistoryLimit>1</passwordHistoryLimit>
<passwordActivationContextExpiry>2</passwordActivationContextExpiry>
<useKnowledgeFactorToken>true</useKnowledgeFactorToken>
<knowledgeFactorToken>email</knowledgeFactorToken>
<newUserPasswordActivationContextExpiry>2</newUserPasswordActivationContextExpiry>
</resp>
SAML Authentication response:
<resp status="ok">
<authType>9</authType>
<authDescription>SAML/ADFS</authDescription>
<APIAuthType>10</APIAuthType>
<authAPIDescription>API Token</authAPIDescription>
<samlName>Salesforce</samlName>
<issuer>https://rmateti-dev-ed.my.salesforce.com</issuer>
<entityId>
http://nbhydrmateti.bedford.progress.com:8830
</entityId>
<samlIdpLoginUrl>
http://nbhydrmateti.bedford.progress.com:8830/router/login/loginSaml
</samlIdpLoginUrl>
<samlIdpLogoutUrl>https://www.twitter.com</samlIdpLogoutUrl>
<samlAttributeMap>
firstName=givenName|lastName=sn|loginName=uid|city=city
</samlAttributeMap>
<samlAuthnContextComparison>minimum</samlAuthnContextComparison>
</resp>
Response when viewing the default authentication profile of a customer
<?xml version="1.0" encoding="UTF-8" ?>
<resp status="ok">
<authProfileId>6fba7e5a-64ab-47e8-ba4b-c360c482e280</authProfileId>
<authType>0</authType>
<authDescription>Password</authDescription>
<APIAuthType>0</APIAuthType>
<authAPIDescription>Password</authAPIDescription>
<useSecQuestions>false</useSecQuestions>
<securityLevel>Low</securityLevel>
<expirPolicy>0</expirPolicy>
<enablePasswordHistory>false</enablePasswordHistory>
<passwordHistoryLimit>1</passwordHistoryLimit>
<passwordActivationContextExpiry>2</passwordActivationContextExpiry>
<newUserPasswordActivationContextExpiry>2</newUserPasswordActivationContextExpiry>
<useKnowledgeFactorToken>false</useKnowledgeFactorToken>
</resp>
getBinaryData
Purpose
Retrieves the file attachment associated with a particular file field from a specific record.
HTTP Method
GET method
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1219
Chapter 15: Reference
URL
https://www.rollbase.com/rest/api/getBinaryData
URL Parameters
sessionId
The session ID obtained from the body of the response when calling login on page 1246.
objName
The object integration name.
id
A long value containing the record ID.
fieldName
A string containing the file field integration name.
output
Optional parameter specifying the output format, which is one of:
• raw (the default) for raw binary output.
• xml for XML output.
• json for JSON output.
Permissions Required
View permission for the requested object type.
Response
The file attachment from the specified file field. The content type and length of output will be set to correspond
to the attachment.
Example
Input example (URL parameters) specifying JSON output:
http://localhost:8080/rest/api/getBinaryData?objName=a&id=806765
&fieldName=My_File&output=json&sessionId=a78c32aeff854b9e91833efd4d304aef@5903
Output example in JSON (fileData truncated):
{ "My_File": { "contentType": "application/octet-stream", "fileName": "Bug.node",
"fileData": "LyoNCiAqIFByb2dyZXNw0KCQl9KTsNCgl9KTsNCn0NCg0K" } }
1220 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Rollbase REST Methods
getBuildStatus
Purpose
Retrieves status of current Rollbase build and license info in XML format.
HTTP Method
GET
URL
https://www.rollbase.com/rest/api/getBuildStatus
URL Parameters
sessionId
The session ID obtained from the body of the response when calling login on page 1246.
output
Optional parameter specifying the output format, one of: xml (default) or json.
Response
Build and license information in XML format.
Example
Sample Response:
<?xml version="1.0" encoding="UTF-8" ?>
<resp status="ok">
<status>
<releaseNo>3.7.4</releaseNo>
<releaseDate>2012-08-16T</releaseDate>
<edition>Multi-Tenant</edition>
<expiration>2013-01-30T</expiration>
<host>localhost:8080</host>
</status>
</resp>
getCodeById
Purpose
Retrieves the integration code of a picklist item or a status by providing its ID.
Note: This API only works when the ID is numeric. Therefore, Picklist(char) or Radio Button(char) are not
supported.
HTTP Method
GET
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1221
Chapter 15: Reference
URL
https://www.rollbase.com/rest/api/getCodeById
URL Parameters
sessionId
The session ID obtained from the body of the response when calling login on page 1246.
objName
The object integration name.
field
The field integration name.
id
Numeric ID of picklist item or status.
output
Optional parameter specifying the output format, one of: xml (default) or json.
Permissions Required
View permission for the requested object type.
Response
Integration code of item with matching ID or null
Example
Output example in JSON:
{ "code": "CREATED" }
getCount
Purpose
Returns the total number of records in a view (see Working with views on page 437 for more information about
views).
HTTP Method
GET
URL
https://www.rollbase.com/rest/api/getCount
1222 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Rollbase REST Methods
URL Parameters
sessionId
The session ID obtained from the body of the response when calling login on page 1246.
viewId
The original view ID.
filterName
Name of the field to filter the output using the “equals” option (replaces the filter set in the view, if
any).
filterValue
Value of the field to filter the output using the "equals" option.
output
Optional parameter specifying the output format, one of: xml (default) or json.
Permissions Required
View permission for the requested object type.
Response
Total number of records in view
Example
Output example in XML:
<resp status="ok">
<count>100</count>
</resp>
Output example in JSON:
{ "count": 100 }
getDataField
Purpose
Retrieves the value of a single field from a specific record.
For external objects (such as those mapped to external tables, to OpenEdge Service objects, or through a D2C
connection), you must specify both the objName and id fields.
HTTP Method
GET
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1223
Chapter 15: Reference
URL
https://www.rollbase.com/rest/api/getDataField
URL Parameters
sessionId
The session ID obtained from the body of the response when calling login on page 1246.
objName
The object integration name.
id
The record ID.
fieldName
The field integration name.
output
Optional parameter specifying the output format, one of: xml (default) or json.
Note:
• The format of date or date/time fields is governed by the shared property UseISODateFormatInRESTJSON
and can be configured from System Console > System > Shared Properties > General > API. For more
information, see Shared Properties.
• The shared property mentioned above is applicable only if the output is in JSON format.
Permissions Required
View permission for the requested object type.
Response
Field's value.
Example
Output example in XML:
<?xml version="1.0" encoding="utf-8" ?>
<resp status="ok">
<Field name="status">Created</Field>
</resp>
Output example in JSON:
{ "status": "Created" }
1224 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Rollbase REST Methods
getDataObj
Purpose
Warning: This method is deprecated. Please change any existing code to use getRecord on page 1235,
which takes an object ID as a parameter.
Retrieves all field data (including formulas) for a given record in XML format.
The composite output is generated recursively in a tree-type structure. The following rules apply:
• The maximum level of recursion is provided as a URL parameter.
• Each data record is included in the output only once.
• No more than 1000 total data records are included in the output.
• The objNames input parameter can be used to explicitly set the list of output data objects.
HTTP Method
GET
URL
https://www.rollbase.com/rest/api/getDataObj
URL Parameters
sessionId
The session ID obtained from the body of the response when calling login on page 1246.
id
The record ID.
composite
The number of levels for related records to be included recursively in the output. Defaults to 0.
objNames
A comma-separated list of object names. If present, only objects from this list are included in the
output.
fieldList
A comma-separated list of field names. If present, only fields from this list are included in the output.
output
Optional parameter specifying the output format, one of: xml (default) or json.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1225
Chapter 15: Reference
Note:
• The format of date or date/time fields is governed by the shared property UseISODateFormatInRESTJSON
and can be configured from System Console > System > Shared Properties > General > API. For more
information, see Shared Properties.
• The shared property mentioned above is applicable only if the output is in JSON format.
Permissions Required
View permission for the requested object type.
Response
All of the field data for the specified object record.
Example
Output example for core record:
<?xml version="1.0" encoding="utf-8" ?>
<resp status="ok">
<data id="131227" objName="person">
<Field name="id">131227</Field>
<Field name="club_member">false</Field>
<Field name="lastName">Smith</Field>
<Field name="status">Created</Field>
<Field name="updatedAt">20110111T143331Z</Field>
</data>
</resp>
Output example for core and related record (composite parameter set to 1):
<?xml version="1.0" encoding="utf-8" ?>
<resp status="ok">
<data id="131227" objName="person">
<Field name="id">131227</Field>
<Field name="club_member">false</Field>
<Field name="lastName">Smith</Field>
<Field name="status">Created</Field>
<Field name="updatedAt">20110111T143331Z</Field>
<Field name="R986">131228,131229</Field>
<composite>
<data id="131228" objName="payment">
<Field name="amount">500.00</Field>
<Field name="paym_date">20110115T143331Z</Field>
<Field name="R986">131227</Field>
</data>
<data id="131229" objName="payment">
<Field name="amount">450.00</Field>
<Field name="paym_date">20110116T143331Z</Field>
<Field name="R986">131227</Field>
</data>
</composite>
</data>
</resp>
1226 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Rollbase REST Methods
getIdByCode
Purpose
Retrieves the ID of a picklist item or status by providing its integration code.
Note: This API only works when the ID is numeric. Therefore, Picklist(char) or Radio Button(char) are not
supported.
HTTP Method
GET
URL
https://www.rollbase.com/rest/api/getIdByCode
URL Parameters
sessionId
The session ID obtained from the body of the response when calling login on page 1246.
objName
The object integration name.
field
The field integration name.
code
Integration name of picklist item or status.
output
Optional parameter specifying the output format, one of: xml (default) or json.
Permissions Required
View permission for the requested object type.
Response
ID of item with matching integration code or -1
Example
Output example in JSON:
{ "id": 4567 }
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1227
Chapter 15: Reference
getIdByOriginalId
Purpose
Given the original ID and an entity type, returns the entity's ID.
HTTP Method
GET
URL
https://www.rollbase.com/rest/api/getIdByOriginalId
URL Parameters
sessionId
The session ID obtained from the body of the response when calling login on page 1246.
entityType
The type of entity. Can be one of object, field, relationship, webpage, view, template,
report, chart, gauge, trigger, process, status, action, button, or datamap.
origId
The original ID of the entity.
output
Optional parameter specifying the output format, one of: xml (default) or json.
Permissions Required
The user must have the Administrator role.
Response
If successful, the ID of the specified entity. If an entity of the specified type with the specified original ID does
not exist, returns an error message in the specified output format (XML or JSON).
Example
The following example retrieves the ID for an object with the original ID 7550.
https://www.rollbase.com/rest/api/getIdByOriginalId?
sessionId=e7bf663caa844ac89dce1c36c17c9300@46216462&entityType=object&origId=7550
The output in XML format:
<?xml version="1.0" encoding="UTF-8" ?>
<resp status="ok">
<id>46219927</id>
</resp>
1228 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Rollbase REST Methods
If the specified entity does not exist, returns an error message as shown below (in XML format):
<?xml version="1.0" encoding="UTF-8" ?>
<resp status="fail">
<err>No object exists with original ID - 7550</err>
</resp>
getLDFIDs
Purpose
Retrieves IDs of LDF nodes (Locations, Departments, or Functions) assigned to the current non-administrative
user. This set of nodes is determined by:
• The groups assigned to current user
• The LDF nodes assigned to these groups
• The hierarchical structure of the LDF nodes
See the LDF Filter field on the user view page for more information.
HTTP Method
GET
URL
https://www.rollbase.com/rest/api/getLDFIDs
URL Parameters
sessionId
The session ID obtained from the body of the response when calling login on page 1246.
objName
The integration name of LDF dimension. It must be one of the following: $ORG_LOCN, $ORG_DEPT,
or $ORG_FUNC.
output
Optional parameter specifying the output format, one of: xml (default) or json.
Response
Returns a comma-separated list of LDF node IDs assigned to the current user. Returns “Full Access” if
the user has full access to all LDF nodes. Returns “No Access” if the user has no access to LDF nodes.
Example
Example output (JSON):
{ "ids": "4567,7890,4567" }
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1229
Chapter 15: Reference
getPage
Purpose
Retrieves the specified range of data records in a view. The selected view defines the sorting and filtering of
output. The amount of processing and time required to get complete results can vary widely, depending on
whether it fetches related records and the number of rows you specify per page.
HTTP Method
GET
URL
https://www.rollbase.com/rest/api/getPage
URL Parameters
sessionId
The session ID obtained from the body of the response when calling login on page 1246.
viewId
The original view ID.
startRow
The number of the row from which to start output. Defaults to 0.
rowsPerPage
The number of data records in the output. Defaults to the user-specified number of records per page.
composite
The number of levels for related records to be included recursively in the output. Defaults to 0.
objNames
A comma-separated list of object names. If present, only objects from this list are included in the
output.
fieldList
A comma-separated list of field names. If present, only fields from this list are included in the output.
filterName
Name of the field to filter the output using the “equals” option (replaces the filter set in the view, if
any).
filterValue
Value of the field to filter the output using the "equals" option.
1230 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Rollbase REST Methods
onlyViewFields
When true, the output only includes fields in the specified view. When false, the output includes
all fields in the object definition.
output
Optional parameter specifying the output format, one of: xml (default) or json.
Note:
• The format of date or date/time fields is governed by the shared property UseISODateFormatInRESTJSON
and can be configured from System Console > System > Shared Properties > General > API. For more
information, see Shared Properties.
• The shared property mentioned above is applicable only if the output is in JSON format.
Permissions Required
View permission for the requested object type.
Response
The set of data records in the view in the requested range
Example
Output example in XML format (no recursive output for related records):
<?xml version="1.0" encoding="utf-8" ?>
<resp status="ok">
<data id="131227" objName="person">
<Field name="firstName">Bill</Field>
<Field name="lastName">Smith</Field>
</data>
<data id="131228" objName="person">
<Field name="firstName">John</Field>
<Field name="lastName">Roth</Field>
</data>
</resp>
Output example in JSON format (no recursive output for related records):
[
{"objName": "lead", "id": 131227, "firstName": "Bill", "lastName": "Smith" },
{"objName": "lead", "id": 131228, "firstName": "John", "lastName": "Roth" }
]
getPermissionsByRole
Purpose
Returns information about all of the entities of the given type, including permissions granted to the specified
role. Throws an exception in the following cases:
• entityType is application, view, report, or chart, and the the specified roleID evaluates to
Server API
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1231
Chapter 15: Reference
• entityType is menu, action, or field, and the specified roleID evaluates to Server API, Portal
Guest, or Portal User
• The specified roleID evaluates to Administrator or No Access
HTTP Method
GET
URL
https://www.rollbase.com/rest/api/getPermissionsByRole
URL Parameters
sessionId
The session ID obtained from the body of the response when calling login on page 1246.
roleId
The original ID of the role.
entityType
The type of entity for which permissions should be listed. Can be one of the following: field, object,
application, menu, view, action, report, chart.
objId
The original ID of the object definition.This is required only when entityType is field, view,
action, report, or chart.
appId
The original ID of the application. This is required only when entityType is menu.
output
Optional parameter specifying the output format, one of: xml (default) or json.
Permissions Required
Full administrative privileges.
Response
The name, ID, original ID, and permissions granted for that role in XML or JSON format. Permissions include
true, false, and, for fields, conditional. See setPermissionsByRole on page 1268 for the possible permissions
for each entity type.
Example
Output example in JSON format for entityType=application:
[
{
"name": "Progress Rollbase",
"id": "46219010",
1232 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Rollbase REST Methods
"originalId": "836899",
"View": "true"
},
{
"name": "Organization Management",
"id": "46219031",
"originalId": "2354424",
"View": "false"
},
{
"name": "Library",
"id": "46219857",
"originalId": "5903",
"View": "true"
},
{
"name": "Room Reservation",
"id": "46220403",
"originalId": "7549",
"View": "false"
},
{
"name": "Order Management",
"id": "46220807",
"originalId": "150491448",
"View": "false"
}
]
getPermissionsByUser
Purpose
Returns information about all of the entities of the given type, including permissions granted to the specified
role. Throws an exception in the following cases:
• entityType is application, view, report, or chart, and the the specified user's role is Server
API
• entityType is menu or action, and the specified user's role is Server API, Portal Guest, or Portal
User
• The specified user's role is Administrator or No Access
• entityType is field, as user-based access control is not supported for fields.
HTTP Method
GET
URL
https://www.rollbase.com/rest/api/getPermissionsByUser
URL Parameters
sessionId
The session ID obtained from the body of the response when calling login on page 1246.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1233
Chapter 15: Reference
userId
The ID of the user.
entityType
The type of entity for which permissions should be listed. Can be one of the following: object,
application, menu, view, action, report, chart.
objId
The original ID of the object definition.This is required only when entityType is view, action,
report, or chart.
appId
The original ID of the Application. This is required only when entityType is menu.
output
Optional parameter specifying the output format, one of: xml (default) or json.
Permissions Required
Full administrative privileges.
Response
The name, ID, original ID, and permissions granted for that user in XML or JSON format. See
setPermissionsByUser on page 1270 for the possible permissions for each entity type.
Example
Output example in JSON format for entityType=object:
[
{
"name": "Product",
"id": "46220471",
"originalId": "151807756",
"View": "false",
"Create": "false",
"Edit": "false",
"Delete": "false"
},
{
"name": "Reservation",
"id": "46219904",
"originalId": "791755",
"View": "true",
"Create": "false",
"Edit": "false",
"Delete": "false"
},
{
"name": "Room",
"id": "46219927",
"originalId": "7550",
"View": "true",
"Create": "true",
"Edit": "true",
"Delete": "true"
1234 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Rollbase REST Methods
}
]
getPicklist
Purpose
Returns items available for the selected Picklist field (including radio buttons and groups of check box fields)
as a JSON array. Each array entry has elements: name, id, and code.
HTTP Method
GET
URL
https://www.rollbase.com/rest/api/getPicklist
URL Parameters
sessionId
The session ID obtained from the body of the response when calling login on page 1246.
objName
The object integration name.
fieldName
The field integration name.
mainValueId
The ID of the main picklist item (optional, for dependent picklists only).
Response
A JSON string of picklist items.
Example
Example output:
[{"code":"S","id":721774,"name":"South"},{"code":"N","id":721775,"name":"North"},
{"code":"E","id":721776,"name":"East"},{"code":"W","id":721777,"name":"West"}]
getRecord
Purpose
Retrieves all field data (including formulas) for a given record in XML format.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1235
Chapter 15: Reference
The composite output is generated recursively in a tree-type structure. The following rules apply:
• The maximum level of recursion is provided as a URL parameter.
• Each data record is included in the output only once.
• No more than 1000 total data records are included in the output.
• The objNames input parameter can be used to explicitly set the list of output data objects.
HTTP Method
GET
URL
https://www.rollbase.com/rest/api/getRecord
URL Parameters
objName
Optional parameter specifying the object integration name.
sessionId
The session ID obtained from the body of the response when calling login on page 1246.
id
The record ID.
composite
Optional parameter specifying the number of levels for related records to be included recursively in
the output. Defaults to 0.
objNames
Optional parameter specifying a comma-separated list of object names. If present, only objects from
this list are included in the output.
fieldList
Optional parameter specifying a comma-separated list of field names. If present, only fields from this
list are included in the output.
output
Optional parameter specifying the output format, one of: xml (default) or json.
Note:
• The format of date or date/time fields is governed by the shared property UseISODateFormatInRESTJSON
and can be configured from System Console > System > Shared Properties > General > API. For more
information, see Shared Properties.
• The shared property mentioned above is applicable only if the output is in JSON format.
1236 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Rollbase REST Methods
Permissions Required
View permission for the requested object type.
Response
All of the field data for the specified object record and related records.
Example
Output example for core record:
<?xml version="1.0" encoding="utf-8" ?>
<resp status="ok">
<data id="131227" objName="person">
<Field name="id">131227</Field>
<Field name="club_member">false</Field>
<Field name="lastName">Smith</Field>
<Field name="status">Created</Field>
<Field name="updatedAt">20110111T143331Z</Field>
</data>
</resp>
Output example for core and related record (composite parameter set to 1):
<?xml version="1.0" encoding="utf-8" ?>
<resp status="ok">
<data id="131227" objName="person">
<Field name="id">131227</Field>
<Field name="club_member">false</Field>
<Field name="lastName">Smith</Field>
<Field name="status">Created</Field>
<Field name="updatedAt">20110111T143331Z</Field>
<Field name="R986">131228,131229</Field>
<composite>
<data id="131228" objName="payment">
<Field name="amount">500.00</Field>
<Field name="paym_date">20110115T143331Z</Field>
<Field name="R986">131227</Field>
</data>
<data id="131229" objName="payment">
<Field name="amount">450.00</Field>
<Field name="paym_date">20110116T143331Z</Field>
<Field name="R986">131227</Field>
</data>
</composite>
</data>
</resp>
getRelationships
Purpose
Retrieves an array of related record IDs. If you supply the optional fieldList parameter is supplied, output
only includes values for those fields.
HTTP Method
GET
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1237
Chapter 15: Reference
URL
https://www.rollbase.com/rest/api/getRelationships
URL Parameters
sessionId
The session ID obtained from the body of the response when calling login on page 1246.
objName
The object integration name.
id
The record ID.
relName
The relationship integration name.
fieldList
A comma-separated list of field names. If present, only fields from this list are included in the output.
output
Optional parameter specifying the output format, one of: xml (default) or json.
Permissions Required
View permission for the requested object type.
Response
IDs of related records
Example
Output example (XML):
<resp status="ok">
<ids>
<id>314452</id>
<id>128003</id>
</ids>
</resp>
Output example (JSON):
[ 314452, 128003 ]
1238 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Rollbase REST Methods
getRoleById
Purpose
Returns information about the specified role in XML or JSON format. Throws an exception if roleId evaluates
to Super Admin.
HTTP Method
GET
URL
https://www.rollbase.com/rest/api/getRoleById
URL Parameters
sessionId
The session ID obtained from the body of the response when calling login on page 1246.
roleId
The original ID of the role.
output
Optional parameter specifying the output format, one of: xml (default) or json.
Permissions Required
Full administrative privileges.
Response
The integration code, name, description, ID, and original ID of the role in XML or JSON format.
Example
Output example in XML format:
<?xml version="1.0" encoding="UTF-8" ?>
<resp status="ok">
<role>
<name>Administrator</name>
<description>System Administrator has unrestricted access to all
applications.</description>
<id>90</id>
<originalId>90</originalId>
</role>
</resp>
Output example in JSON format:
{
"code": null,
"name": "Administrator",
"description": "System Administrator has unrestricted access to all applications.",
"id": "90",
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1239
Chapter 15: Reference
"originalId": "90"
}
getRoles
Purpose
Returns a list in XML or JSON format of all the roles in the tenant with the following details:
• Name
• Integration code
• Description
• ID
• Original ID
Does not include the Super Admin role in the response.
HTTP Method
GET
URL
https://www.rollbase.com/rest/api/getRoles
URL Parameters
sessionId
The session ID obtained from the body of the response when calling login on page 1246.
output
Optional parameter specifying the output format, one of: xml (default) or json.
Permissions Required
Full administrative privileges.
Response
A list of all roles in the tenant in XML or JSON format.
Example
Output example in JSON format:
[
{
"name": "Server API",
"code": null,
"description": "System role used to check permissions in Server-side API calls.",
"id": "98",
"originalId": "98"
},
1240 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Rollbase REST Methods
{
"name": "Portal Guest",
"code": null,
"description": "System role used to assign permissions to non-authenticated portal
users.",
"id": "99",
"originalId": "99"
},
{
"name": "Library Employee",
"code": null,
"description": null,
"id": "67956084",
"originalId": "67956084"
},
{
"name": "Administrator",
"code": null,
"description": "System Administrator has unrestricted access to all applications.",
"id": "90",
"originalId": "90"
},
{
"name": "Portal User",
"code": null,
"description": "System role used to assign permissions to authenticated portal
users.",
"id": "93",
"originalId": "93"
},
{
"name": "No Access",
"code": null,
"description": "",
"id": "94",
"originalId": "94"
}
]
getTopology
Purpose
Retrieves topology. Only a user with the Administrator role on the master tenant can execute this method.
HTTP Method
GET
URL
https://www.rollbase.com/rest/api/getTopology
URL Parameters
sessionId
The session ID obtained from the body of the response when calling login() on page 1351.
Permissions Required
Administrative privileges on the master tenant.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1241
Chapter 15: Reference
Response
Topology details in JSON format.
Example
Output example:
{
"topology": [
{
"nodeName": "129e5305-0f2a-48ca-9a92-13b606ec36a4",
"hostName": "localhost",
"port": 8080,
"components": [
{
"componentName": "STORAGE",
"componentDisplayName": "STORAGE server",
"componentType": "STORAGE",
"internalURL": "http://localhost:8080/storage/",
"externalURL": "http://abc:8080/storage/",
"componentURL": "http://localhost:8080/storage/servlet/Component"
},
{
"componentName": "REST",
"componentDisplayName": "REST server",
"componentType": "REST",
"internalURL": "http://localhost:8080/rest/",
"externalURL": "http://abc.com:8080/rest/",
"componentURL": "http://localhost:8080/rest/servlet/Component"
}
]
},
{
"nodeName": "6ded8814-d3cc-41b4-baa1-11f96df018b4",
"hostName": "localhost",
"port": 9180,
"components": [
{
"componentName": "PROD1",
"componentDisplayName": "PROD1 server",
"componentType": "PROD",
"internalURL": "http://localhost:9180/prod1/",
"externalURL": "http://abc.com:8080/prod1/",
"componentURL": "http://localhost:9180/prod1/servlet/Component",
"power": 1,
"isDedicated": false
}
]
},
{
"nodeName": "b369e4a2-adaf-4571-97ee-1e762a770eac",
"hostName": "localhost",
"port": 9080,
"components": [
{
"componentName": "PROD1",
"componentDisplayName": "PROD1 server",
"componentType": "PROD",
"internalURL": "http://localhost:9080/prod1/",
"externalURL": "http://abc.com:8080/prod1/",
"componentURL": "http://localhost:9080/prod1/servlet/Component",
"power": 1,
"isDedicated": false
}
]
}
]
}
1242 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Rollbase REST Methods
getUpdated
Purpose
Retrieves an array of record IDs of the specified object type that were either created or updated within the
given date/time interval. This method is not available for external objects, including those mapped to OpenEdge
service objects.
HTTP Method
GET
URL
https://www.rollbase.com/rest/api/getUpdated
URL Parameters
sessionId
The session ID obtained from the body of the response when calling login on page 1246.
objName
The object integration name.
from
Beginning of date/time interval in ISO 8601 format.
till
End of date/time interval in ISO 8601 format.
output
Optional parameter specifying the output format, one of: xml (default) or json.
Permissions Required
View permission for the requested object type.
Response
IDs of all records found in the search, returned as an array of longs
Example
Output example in XML:
<resp status="ok">
<ids>
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1243
Chapter 15: Reference
<id>314452</id>
<id>128003</id>
</ids>
</resp>
Output example in JSON:
[ 314452, 128003 ]
install
Purpose
Installs or updates Rollbase application from an XML document. Invoking this API will cause a customer reload.
All currently logged users will be forced to log out.
HTTP Method
GET
URL
https://www.rollbase.com/rest/api/install
URL Parameters
sessionId
The session ID obtained from the body of the response when calling login on page 1246.
overrideChanges
A value of true or false. If true (default value), override changes made by administrative users.
output
Optional parameter specifying the output format, one of: xml (default) or json.
Request Body
Application XML.
Permissions Required
Full administrative privileges.
Response
Short report on application installation/update
Example
Output example:
<resp status="ok">
<Report>Application "Test" has been installed.</Report>
</resp>
1244 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Rollbase REST Methods
installByAppId
Purpose
Installs or updates a Rollbase application published to the Marketplace or Application Directory. Invoking
this API will cause customer reload. All currently logged in users will be forced to log out.
HTTP Method
POST
URL
https://www.rollbase.com/rest/api/installByAppId
URL Parameters
sessionId
The session ID obtained from the body of the response when calling login on page 1246.
id
ID of package record created for published application in Application Directory or Marketplace.
overrideChanges
A value of true or false. If true (default value), override changes made by administrative users.
output
Optional parameter specifying the output format, one of: xml (default) or json.
Permissions Required
Full administrative privileges.
Response
Short report on application installation/update
Example
Output example:
<resp status="ok">
<Report>Application "Test" has been installed.</Report>
</resp>
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1245
Chapter 15: Reference
licenseUpdate
Purpose
Updates the license for a running Rollbase instance based on the supplied xmlString. Only a user with the
Administrator role on the master tenant can execute this method. This method is only available on Rollbase
Private Cloud.
HTTP Method
POST
URL
https://www.rollbase.com/rest/api/licenseUpdate
URL Parameters
sessionId
The session ID obtained from the body of the response when calling login on page 1246.
xmlString
A valid license XML string.
Permissions Required
Administrative privileges on the master tenant.
Response
Returns the status in JSON format.
Example
The following example is the response upon a successful license update:
{"status":"ok"}
login
Purpose
Performs a user log in and initiates an API session. This method must be called prior to any other API call. The
REST login creates a server-side session that may expire according to the security level selected for a
Customer (see Security and Access Control for more info). The API client should log in again if the session
expires. Progress recommends that an API client logs out after performing a group of operations rather than
keeping the session open for a long time. When an API client logs in, any previous sessions existing for the
same user credentials are terminated.
Master Server users with login permissions can use the login API with their credentials to access the REST
API for a specified Customer.
1246 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Rollbase REST Methods
HTTP method
POST or GET
URL
https://www.rollbase.com/rest/api/login
HTTP header parameters
loginName
Login name for an active Rollbase user account.
password
User password.
custId
ID of the Customer to log in. Optional parameter: if not present, the Customer is determined by login
name.
URL parameters
loginName
Login name for an active Rollbase user account. This parameter is deprecated. Please change any
existing code to use the HTTP header parameter described above.
password
User password. This parameter is deprecated. Please change any existing code to use the HTTP
header parameter described above.
custId
ID of the Customer to log in. Optional parameter: if not present, the Customer is determined by login
name. This parameter is deprecated. Please change any existing code to use the HTTP header
parameter described above.
output
Optional parameter specifying the output format, one of: xml (default) or json.
adminFallback
When true, enables the to fallback to the default password authentication if the tenant uses a
different authentication method. Defaults to false. This parameter can also be specified in the
HTTP header.
Response
Session ID that must be used in all subsequent API calls during this session
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1247
Chapter 15: Reference
Example
Sample XML response:
<?xml version="1.0" encoding="utf-8" ?>
<resp status="ok">
<sessionId> ecc701d2442e4f6b9fe2a7cc7b52078a@5857</sessionId>
</resp>
Sample JSON response:
{"status":"ok", "sessionId":"ecc701d2442e4f6b9fe2a7cc7b52078a@5857" }
logout
Purpose
Terminates the specified API session. This method should be called to explicitly end each Web API session.
The output parameter is optional.
HTTP Method
GET
URL
https://www.rollbase.com/rest/api/logout
URL Parameters
sessionId
The session ID obtained from the body of the response when calling login on page 1246.
output
Optional parameter specifying the output format, one of: xml (default) or json.
Response
Standard success or failure output
Example
Sample XML response:
<?xml version="1.0" encoding="utf-8" ?>
<resp status="ok">
</resp>
resetPassword
Purpose
Resets the password of the specified user.
1248 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Rollbase REST Methods
HTTP Method
POST
URL
https://www.rollbase.com/rest/api/resetPassword
URL Parameters
sessionId
The session ID obtained from the body of the response when calling login on page 1246.
loginName
Login name for an active Rollbase user account in the same tenant
output
Optional parameter specifying the output format, one of: xml (default) or json.
Permissions Required
Requires administrative privileges. Establish the session by logging in with credentials for an administrative
user.
runAction
Purpose
Runs a workflow action on a record.
HTTP Method
POST
URL
https://www.rollbase.com/rest/api/runAction
URL Parameters
sessionId
The session ID obtained from the body of the response when calling login on page 1246.
objName
The object integration name.
id
The record ID.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1249
Chapter 15: Reference
actionId
The original ID of the workflow action to run.
output
Optional parameter specifying the output format, one of: xml (default) or json.
Additional parameters
The integration name(s) of field(s) to be updated as part of the workflow action. If the workflow action
type is Status Change, the Use Web Page property must be specified on the action for fields to be
updated. See Status Change action on page 269 for details.
Permissions Required
Edit permission for the requested object type.
Response
The status in XML or JSON format. The following is an XML response upon success:
<?xml version="1.0" encoding="UTF-8" ?>
<resp status="ok"></resp>
The following is a JSON response upon failure:
{
"status": "fail",
"message": "Action with original id 225886927 not applicable on the data record."
}
If the workflow action is of the type Related Record, the response includes the ID of the newly created record
(see example below). Note that a conversion map or a record template is required to run a Related Record
workflow action to create a record of a different object type; if neither is specified, the related record is not
created. If the action creates a record of the same object type, a record will get created with the same data as
the record on which the workflow action is being executed. See Related Record action on page 270 for details.
Example
The following example creates a new related record for an Order record and sets the value of the Product field:
https://www.rollbase.com/rest/api/runAction?sessionId=d802a98210e9447c95691e36b1e79f28@148219868
&objName=Order&id=203783751&actionId=226380776&Product=Cheese&output=xml
The response includes the ID of the new record:
<?xml version="1.0" encoding="UTF-8" ?>
<resp status="ok">
<data id="366891304"></data>
</resp>
runTrigger
Purpose
Runs a trigger on an object.
1250 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Rollbase REST Methods
HTTP Method
PUT or POST
URL
https://www.rollbase.com/rest/api/runTrigger
URL Parameters
sessionId
The session ID obtained from the body of the response when calling login on page 1246.
objName
Optional integration name to narrow the search to a particular object.
id
The record ID.
triggerId
Integration name or the original ID of the trigger.
checkValidation
If set to true, checks validation formula before running the trigger. This is set to false by default.
runRecursions
When true, configures the trigger to run recursively, if recursive properties on the trigger definition
page are set. Defaults to false if the parameter is not set.
output
Optional parameter specifying the output format, one of: xml (default) or json.
Response
Standard success or failure output.
Permissions
Edit permission for the requested object type.
Example
Input example (URL parameters):
&objName=person&id=314452&triggerId=TR1
Output example (in XML format):
<?xml version="1.0" encoding="UTF-8"?>
<resp status="ok"> </resp>
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1251
Chapter 15: Reference
search
Purpose
Performs a full-text search in the database assigned to the account used to obtain the session ID. The search
query has the same syntax as that used in the standard Rollbase interface. See Views and Search for more
information on search query syntax.
HTTP Method
GET
URL
https://www.rollbase.com/rest/api/search
URL Parameters
sessionId
The session ID obtained from the body of the response when calling login on page 1246.
output
Optional parameter specifying the output format, one of: xml (default) or json.
query
A URL-encoded SQL query that adheres to the same syntax and restrictions as the server-side
Query API.
objName
Optional integration name to narrow the search to a particular object.
Response
IDs of all records found in the search, returned as an array of longs
Example
Output example (XML):
<resp status="ok">
<ids>
<id>314452</id>
<id>128003</id>
</ids>
</resp>
Output example (JSON):
[ 314452, 128003 ]
1252 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Rollbase REST Methods
selectNumber
Purpose
Runs an SQL SELECT query on the server and returns the first element of the results as a decimal number.
HTTP Method
GET
URL
https://www.rollbase.com/rest/api/selectNumber
URL Parameters
sessionId
The session ID obtained from the body of the response when calling login on page 1246.
output
Optional parameter specifying the output format, one of: xml (default) or json.
query
A text pattern to search.
Permissions Required
View permission for the requested object type.
Response
Query result as decimal number
Example
Output: first element returned by query converted into number and wrapped in XML. Example:
<?xml version="1.0" encoding="UTF-8"?>
<resp status="ok">
<value>53</value>
</resp>
Output example in JSON:
{ "value": 53.0 }
selectQuery
Purpose
Runs an SQL SELECT query on the server and returns the results as a 2D-array.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1253
Chapter 15: Reference
The SELECT query used in this method consists of the following parts:
• The SELECT statement expects columns or expressions to be selected (mandatory). Use the field integration
names as SQL column names. You can use expressions such as COUNT(1). You cannot use * to retrieve
all columns.
• The FROM clause must consist of exactly one object name (mandatory).
• The WHERE clause can include a valid SQL expression to narrow the selection (optional). Use field integration
names as SQL column names.
• The ORDER BY clause can include a valid SQL expression to order the selection (optional). Use field
integration names as SQL column names.
You can use special tokens in your queries such as:
• TODAY for current time
• WEEK for 12PM of last Sunday
• MONTH for 12PM of 1st day of current month
• QUARTER for 12PM of 1st day of current quarter
• YEAR for 12PM of 1st day of current year
• CURR_USER for id of currently logged in user
Object and Field names are case-sensitive, while other components of the SQL query are not.
Use #code suffix to fetch integration codes for picklist fields rather than IDs. See Adding Logic to an Application
for more information.
HTTP Method
GET
URL
https://www.rollbase.com/rest/api/selectQuery
URL Parameters
sessionId
The session ID obtained from the body of the response when calling login on page 1246.
startRow
The number of the row from which to start output. Defaults to 0.
maxRows
The maximum number of rows in the output, which can be configured per Rollbase instance.
query
A text pattern to search.
output
The output format, one of: xml (default), json, or csv.
1254 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Rollbase REST Methods
Note:
• The format of date or date/time fields is governed by the shared properties UseISODateFormatInRESTJSON
& UseISODateFormatInRESTXMLQuery and can be configured from System Console > System >
Shared Properties > General > API. For more information, see Shared Properties.
• The shared properties mentioned above are applicable only if the output is in JSON format.
Permissions Required
The current user requires View permission on the selected object type to run this API.
Response
Query results as 2D array
Example
Query to run:
select id, firstName, lastName from lead oder by updatedAt desc
startRow=0
maxRows=2
Output example in XML:
<?xml version="1.0" encoding="utf-8" ?>
<resp status="ok">
<row>
<col>131227</col>
<col>Bill</col>
<col>Smith</col>
</row>
<row>
<col>131228</col>
<col>John</col>
<col>Roth</col>
</row></resp>
Output example in JSON:
[
[ 131227, "Bill", "Smith" ],
[ 131228, "John", "Roth" ]
]
selectValue
Purpose
Runs an SQL SELECT query on the server and returns the first element from the results as single value.
HTTP Method
GET
URL
https://www.rollbase.com/rest/api/selectValue
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1255
Chapter 15: Reference
URL Parameters
sessionId
The session ID obtained from the body of the response when calling login on page 1246.
output
Optional parameter specifying the output format, one of: xml (default) or json.
query
A text pattern to search.
Note:
• The format of date or date/time fields is governed by the shared properties UseISODateFormatInRESTJSON
& UseISODateFormatInRESTXMLQuery and can be configured from System Console > System >
Shared Properties > General > API. For more information, see Shared Properties.
• The shared properties mentioned above are applicable only if the output is in JSON format.
Permissions Required
The current user requires View permission on the selected object type to run this API.
Response
Query result as single value
Example
Example of first element returned by query wrapped in XML:
<?xml version="1.0" encoding="UTF-8"?>
<resp status="ok">
<value>53</value>
</resp>
Output example in JSON:
{ "value": 53.0 }
setAuthentication
Purpose
Sets the authentication settings of default authentication profile of the tenant to edit it.
HTTP Method
POST
1256 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Rollbase REST Methods
URL
https://www.rollbase.com/rest/api/setAuthentication
URL Parameters
sessionId
The session ID obtained from the body of the response when calling login on page 1246.
output
Optional parameter specifying the output format, one of: xml (default) or json.
authType
Specifies the authentication type. Valid values are:
• 0 — Password. See Password Authentication on page 840 for more information.
• 1 — LDAP. See Configuring LDAP Authentication on page 849 for more information.
• 2 — HTTP POST. See Configuring HTTP POST Authentication on page 851 for more information.
• 3 — HTTP GET. See Configuring HTTP GET Authentication on page 852 for more information.
• 4 — Custom
• 6 — OpenEdge. See Configuring OpenEdge Authentication on page 852 for more information.
• 7 — LDAP Advanced. See Configuring LDAP Advanced Authentication on page 849 for more
information.
• 8 — Kerberos. See Configuring Kerberos Authentication on page 856 for more information.
• 9 — SAML/ADFS. See Configuring SAML/ADFS Authentication on page 857 for more information.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1257
Chapter 15: Reference
The following are the parameters for Password authentication.
• formula
The custom validation formula.
• useSecQuestions
A true value specifies that users must create and answer security questions.
• mustAnswerQuestionsInProfile
The number of security questions a user must answer. Valid values are 2, 3, and 4.
• mustAnswerPreviouslyAnswered
The number of previously answered security questions a user must answer to be authenticated.
Valid values are 1 and 2.
• securityLevel
The security level as a number, where 1=low, 2=medium, and 3=high.
• expirPolicy
The number of days before a password expires. Set to 0 for no password expiration (the default)
and a value of at least the value of the shared property MinExpirationPolicy (30 by default)
otherwise. For OpenEdge authentication, the parameter managePassword must be true in
order to set this parameter.
• questionX
Security questions, where X is a number between 0 and 11. A maximum of 12 security questions
is allowed.
• useKnowledgeFactorToken
This must be set to true to use a knowledge factor token. See User authentication and password
management on page 680 for more information.
• knowledgeFactorToken
This must be a mandatory field from the User object definition that can be configured as a token.
See User authentication and password management on page 680 for more information.
• passwordActivationContextExpiry
The password activation link expiry time. See User authentication and password management
on page 680 for more information.
• newUserPasswordActivationContextExpiry
1258 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Rollbase REST Methods
This is the activation link expiry time. See User authentication and password management on
page 680 for more information.
The following are the parameters for LDAP authentication.
• targetURL
This is the mandatory target URL.
• securityAuthentication
The authentication mechanism to implement. See Configuring LDAP Authentication on page 849
for details.
• securityPrincipal
The name of the user or program doing the authentication. Typically, this is a query string to
search the LDAP database.
• securityCredential
The credentials of the user or program doing the authentication.
• additionalParamKeys
A JSON array of keys for additional parameters. Only one additional parameter is currently
allowed.
• additionalParamValues
A JSON array of values for additional parameters. Only one additional parameter is currently
allowed.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1259
Chapter 15: Reference
The following are the parameters for HTTP POST authentication.
• targetURL
This is the mandatory target URL.
• responseText
This is the mandatory text that must be present in HTTP response to indicate whether the
authentication was successful.
• httpBody
The template for the body of the HTTP POST request (typically a SOAP call). This must include
tokens for user input.
• headerKeys
A JSON array of header keys. The first header key for HTTP POST must always be
Content-Type. Only five headers are currently allowed.
• headerValues
A JSON array of header values. The first header value for HTTP POST must be the content type.
Only five headers are currently allowed.
The following are the parameters for HTTP GET authentication.
• targetURL
This is the mandatory target URL.
• responseText
This is the mandatory text that must be present in HTTP response to indicate whether the
authentication was successful.
• httpBody
The template for the body of the HTTP POST request (typically a SOAP call). This must include
tokens for user input.
• headerKeys
A JSON array of header keys. The first header key for HTTP POST must always be
Content-Type. Only five headers are currently allowed.
• headerValues
A JSON array of header values. The first header value for HTTP POST must be the content type.
Only five headers are currently allowed.
1260 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Rollbase REST Methods
The following are the parameters for OpenEdge authentication.
• realmURL
This is the mandatory realm URL. See Configuring OpenEdge Authentication on page 852 for
details.
• realmClass
This is the mandatory realm class. See Configuring OpenEdge Authentication on page 852 for
details.
• openEdgeDomain
The name of the domain to which the OpenEdge user must belong. See Configuring OpenEdge
Authentication on page 852 for details.
• openEdgeAccessCode
The code or key required for an OpenEdge user to access the OpenEdge domain. See Configuring
OpenEdge Authentication on page 852 for details.
• noHostVerify
If true, OpenEdge authentication will not validate the hostname of the OpenEdge realm URL.
See Configuring OpenEdge Authentication on page 852 for details.
• managePassword
Enables password management options. See Configuring OpenEdge Authentication on page 852
for details.
• passwordGuidelines
The text on the Change Password page that describes password guidelines. The
managePassword parameter must be true in order to set this parameter.
• suLoginname
The Super Admin login name.
• suPassword
The Super Admin password.
• guestLoginname
The guest login name.
• guestPassword
The guest password.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1261
Chapter 15: Reference
• certJarFileContent
The certificate JAR file content. It should be a Base64 encoded string.
• certJarFileName
The certificate JAR file name.
• certJarFileContentType
The certificate JAR file content type.
• tokenFileContent
The token file content. It should be a Base64 encoded string.
• tokenFileName
The token file name.
• tokenFileContentType
The token file content type.
1262 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Rollbase REST Methods
The following are the parameters for LDAP Advanced authentication.
• targetURL
This is the mandatory target URL.
• baseDistinguishedName
The root distinguished name (DN) to use while running queries against your directory server. See
Configuring LDAP Advanced Authentication on page 849 for more information.
• additionalUserDN
The value to be used in addition to the base DN when searching for and loading users. See
Configuring LDAP Advanced Authentication on page 849 for more information.
• authenticationType
The authentication mechanism to implement. See Configuring LDAP Advanced Authentication
on page 849 for more information.
• searchCapabilities
The LDAP authentication requirements to search for and get results from a search query. Valid
values are Anonymous and Authenticated. See Configuring LDAP Advanced Authentication
on page 849 for more information.
• adminSecurityPrincipal
The admin security principal. This parameter is only applicable if searchCapabilities is
Authenticated. See Configuring LDAP Advanced Authentication on page 849 for more
information.
• adminSecurityCredential
The admin security credential. This parameter is only applicable if searchCapabilities is
Authenticated. See Configuring LDAP Advanced Authentication on page 849 for more
information.
• userNameAttribute
The attribute field to use when loading the user name. See Configuring LDAP Advanced
Authentication on page 849 for more information.
• additionalParamKeys
A JSON array of keys for additional parameters. Only one additional parameter is currently
allowed.
• additionalParamValues
A JSON array of values for additional parameters. Only one additional parameter is currently
allowed.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1263
Chapter 15: Reference
The following are the parameters for SAML authentication.
• samlAttributeMap
These are the mandatory URL encoded values. Providing the loginName attribute mapping is
compulsory.
• idpCertificateFileContent
This is the mandatory content of the IDP metadata file.
Note: Before encoding the URL, the file content should be encoded to base 64 with ISO-8859-1
charset.
• issuer
This is the mandatory value of the entityID attribute of the EntityDescriptor element in the IdP
metadata file.
• entityId
This is the mandatory entity ID of the service provider. This is the value of the entityID attribute
of the EntityDescriptor element in the SP metadata file.
• samlAuthnContextComparison
This must be set to one of the four comparison values (better, exact, maximum and minimum).
If no value is set or some random value is set, the value will automatically default to the value
minimum. See Configuring SAML/ADFS Authentication for a Tenant on page 859 for more
information.
• samlIdpLoginUrl
The URL the users of the tenant should use to initiate SAML login. This is the value of the Location
attribute in the SingleSignOnService element for the HTTP-POST binding in the IdP metadata
file.
• samlIdpLogoutUrl
A custom URL can be configured by the SAML customer administrator to redirect the user after
logout.
• idpFileContentType
The file type of the IdP content, that is, MIME. As an XML file will be sent, it is indicated as
application/xml.
• samlAssertionConsumerIndex
The index of the URLs to be used in the SP metadata. In general, multiple URLs are not supported
by most of the IdPs, so you can set this to the default of 0.
1264 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Rollbase REST Methods
• requestSignatureMethod
A signature method alogorithm to be used to sign the request being sent to the IDP. The supported
algorithms are RSA-SHA1 and RSA-SHA256. The default value is RSA-SHA1.
Permissions Required
Full administrative privileges.
Response
The authentication for the tenant in JSON format.
Sample JSON output
{"status":"ok" }
Sample invalid response
{
"status":"fail",
"message":"You cannot edit the authentication type which is not a default authentication
profile."
}
setBinaryData
Purpose
Sets the binary data (file attachment) associated with a particular file field from a specific record.
HTTP Method
GET or POST
URL
https://www.rollbase.com/rest/api/setBinaryData
URL Parameters
id
Record's id.
fieldName
The field integration name.
value
Value to be set. Must be formatted the same way as values in spreadsheet imports. For File Upload
fields: Base-64 encoded binary value of file.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1265
Chapter 15: Reference
contentType
For File Upload fields only: MIME content type of uploaded data .
fileName
For File Upload fields only: original name of file being uploaded.
output
Optional parameter specifying the output format, one of: xml (default) or json.
sessionId
The session ID obtained from the body of the response when calling login on page 1246.
Permissions Required
Edit permission for the requested object type.
Response
Status message wrapped in XML
Example
The following example uploads documents.
import java.io.File;
import java.io.FileInputStream;
import org.apache.commons.codec.binary.Base64;
import org.apache.commons.httpclient.HttpClient;
import org.apache.commons.httpclient.methods.PostMethod;
import org.apache.commons.httpclient.methods.multipart.MultipartRequestEntity;
import org.apache.commons.httpclient.methods.multipart.Part;
import org.apache.commons.httpclient.methods.multipart.StringPart;
public class TestSetBinaryData {
public static void main(String[] args) {
// Apache HTTP client 3.1
PostMethod post = new PostMethod();
HttpClient httpclient = new HttpClient();
String postResponse = null;
try {
post = new PostMethod(
"https://www.rollbase.com/rest/api/
setBinaryData?sessionId=0bb05ac9c5074ebb9d3d460cc7f48696@2722356");
// Multi-part upload
Part[] p1 = new Part[6];
p1[0] = new StringPart("id", "97062227"); // record id
p1[1] = new StringPart("objName", "Object1");
// object integration name
p1[2] = new StringPart("fieldName", "Field1");
// field integration name
p1[3] = new StringPart("contentType", "application/pdf");
// file content type
p1[4] = new StringPart("fileName", "abc.pdf");
// file name
File f = new File("C:\\BinaryFileTest\\abc.pdf");
// actual file
FileInputStream fileInputStream = null;
byte[] bFile = new byte[(int) f.length()];
try {
fileInputStream = new FileInputStream(f);
fileInputStream.read(bFile);
fileInputStream.close();
1266 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Rollbase REST Methods
} catch (Exception e) {
e.printStackTrace();
}
String encodeBase64Str = Base64.encodeBase64String(bFile);
// Convert to Base64 encoded format
System.out.println("length is " + encodeBase64Str.length());
p1[5] = new StringPart("value", encodeBase64Str);
post.setRequestEntity(new MultipartRequestEntity(p1, post.getParams()));
httpclient.executeMethod(post);
postResponse = post.getResponseBodyAsString();
System.out.println("Response is" + postResponse);
} catch (Exception e) {
e.printStackTrace();
} finally {
post.releaseConnection();
}
}
}
setDataField
Purpose
Sets the value of a single field for a specific record.
For external objects (such as those mapped to external tables, to OpenEdge Service objects, or through a D2C
connection), you must specify both the objName and id fields.
HTTP Method
GET or POST
URL
https://www.rollbase.com/rest/api/setDataField
URL Parameters
sessionId
The session ID obtained from the body of the response when calling login on page 1246.
objName
The object integration name.
id
The record ID.
fieldName
The field integration name.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1267
Chapter 15: Reference
value
Value to be set. Must be formatted the same way as values in spreadsheet imports. For File Upload
fields: Base-64 encoded binary value of file.
contentType
For File Upload fields only: MIME content type of uploaded data.
fileName
For File Upload fields only: original name of file being uploaded.
output
Optional parameter specifying the output format, one of: xml (default) or json.
Permissions Required
Edit permission for the requested object type.
Response
Status message wrapped in XML
Example
Output example:
<?xml version="1.0" encoding="utf-8" ?>
<resp status="ok">
<Msg>Field "amount" has been updated</Msg>
</resp>
setPermissionsByRole
Purpose
Sets the permissions for the specified role on the specified entity and returns a status.
HTTP Method
POST
URL
https://www.rollbase.com/rest/api/setPermissionsByRole
URL Parameters
sessionId
The session ID obtained from the body of the response when calling login on page 1246.
1268 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Rollbase REST Methods
roleId
The original ID of the role.
entityType
The type of entity for which permissions should be set. Can be one of the following: field, object,
application, menu, view, action, report, chart.
entityId
The original ID of the entity for which permissions are to be set.
permissions
A comma-separated list of the permissions to set for the entity. Can be any of the following values:
view, create, edit, delete, login. An empty value clears all permissions on the entity for that
role. To grant edit permission on an entity, you must also grant view permission. You can set
login only on a master tenant when entityType is object and entityId evaluates to Customer.
Note that when entityType is application, menu, view, action, report, or chart, the only
valid permission is view.
viewConditionScript
When granting conditional permission for view access, the condition formula as a base64-encoded
string. To grant conditional view permission, the permissions parameter must include view. This
parameter only applies to field-level permissions.
editConditionScript
When granting conditional permission for edit access, the condition formula as a base64-encoded
string. To grant conditional edit permission, the permissions parameter must include view and
edit. This parameter only applies to field-level permissions.
output
Optional parameter specifying the output format, one of: xml (default) or json.
Permissions Required
Full administrative privileges.
Response
The status in XML or JSON format.
Example
Output example in XML format:
<?xml version="1.0" encoding="UTF-8" ?>
<resp status="ok">
</resp>
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1269
Chapter 15: Reference
setPermissionsByUser
Purpose
Sets the permissions for the specified user on the specified entity and returns a status. Throws an exception
if entityType is field, as user-based access control is not supported for fields.
HTTP Method
POST
URL
https://www.rollbase.com/rest/api/setPermissionsByUser
URL Parameters
sessionId
The session ID obtained from the body of the response when calling login on page 1246.
userId
The ID of the user.
entityType
The type of entity for which permissions should be set. Can be one of the following: object,
application, menu, view, action, report, chart.
entityId
The original ID of the entity for which permissions are to be set.
permissions
A comma-separated list of the permissions to be give to the entity. Can be any of the following values:
view, create, edit, delete, login. An empty value clears all permissions on the entity for that
role. You can set login only on a master tenant when entityType is object and entityId
evaluates to Customer. Note that when entityType is application, menu, view, action,
report, or chart, the only valid permission is view.
output
Optional parameter specifying the output format, one of: xml (default) or json.
Permissions Required
Full administrative privileges.
Response
The status in XML or JSON format.
1270 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Rollbase REST Methods
Example
Output example in XML format:
<?xml version="1.0" encoding="UTF-8" ?>
<resp status="ok">
</resp>
update
Purpose
Updates an existing data record and, optionally, related records from values passed in as an XML document.
Note: Do not use this method with PHP CURL. Instead use update2
HTTP Method
PUT or POST
URL
https://www.rollbase.com/rest/api/update
URL Parameters
sessionId
The session ID obtained from the body of the response when calling login on page 1246.
objName
The object integration name.
Request Body
XML document valid record ID, "useIds" attribute (true or false - same meaning as in the Web
API) and data Fields to be updated (see example below). You only need to include the Fields that
should be changed; Fields not included will remain unchanged.
Permissions Required
Edit permission for the requested object type.
Response
Standard success or failure output.
Example
Input example:
<?xml version="1.0" encoding="utf-8" ?>
<data objName="person" id="314452" useIds="false">
<Field name="club_member">false</Field>
<Field name="lastName">Smith</Field>
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1271
Chapter 15: Reference
<Field name="status">Created</Field>
</data>
Output example:
<resp status="ok">
<Msg>12 fields have been processed.</Msg>
</resp>
Like create, update can be used to update several related records in one call. To do that, include a composite
XML node that wraps a set of data XML nodes with valid id attributes as described above. Records
corresponding to each "data" XML node are updated. These updated nodes will have a relationship with the
core record.
Consider this example with dependent nodes:
<?xml version="1.0" encoding="utf-8" ?>
<data objName="person" id="314452" useIds="false">
<Field name="club_member">false</Field>
<Field name="lastName">Smith</Field>
<Field name="status">Created</Field>
<composite>
<data objName="payment" id="314453" useIds="false">
<Field name="amount">500.00</Field>
<Field name="paym_date">09/12/2011</Field>
</data>
<data objName="payment" id="314454" useIds="false">
<Field name="amount">450.00</Field>
<Field name="paym_date">09/22/2011</Field>
</data>
</composite>
</data>
This XML updates one existing record and two related records in one call. Output example:
<resp status="ok">
<data id="314452"/>
<Msg>12 fields have been processed. 2 related records have been updated.</Msg>
</resp>
updateArr
Purpose
Updates a group of records using data from an XML document.
HTTP Method
POST
URL
https://www.rollbase.com/rest/api/updateArr
URL Parameters
sessionId
The session ID obtained from the body of the response when calling login on page 1246.
1272 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Rollbase REST Methods
objName
The object integration name.
output
Optional parameter specifying the output format, one of: xml (default) or json.
Request Body
An XML document with valid id and useIds attributes (true or false) and data fields to be
updated, wrapped in <data> XML nodes (see example below). You only need to include the fields
to be changed; all fields not included will remain unchanged.
Required Permissions
Edit permission for the requested object types.
Response
Standard success or failure output.
Example
Input example:
<?xml version="1.0" encoding="utf-8" ?>
<request>
<data id="314452" useIds="false">
<Field name="club_member">true</Field>
</data>
<data id="314453" useIds="false">
<Field name="lastName">Gray</Field>
</data>
<request>
Output example:
<resp status="ok">
<Msg>2 records have been updated.</Msg>
</resp>
updateCustomer
Purpose
Updates a customer record using data from the URL parameters. For private cloud users, the user credentials
for the user making this request must stored on the Master server. The output parameter is optional.
HTTP Method
POST
URL
https://www.rollbase.com/rest/api/updateCustomer
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1273
Chapter 15: Reference
URL Parameters
sessionId
The session ID obtained from the body of the response when calling login on page 1246.
id
The ID of the Customer record.
useIds
Boolean value: if true, use numeric IDs for lookup and picklist values, otherwise use integration codes
and record names.
field1;[field2; ...]
Parameter's name - integration name of field to set; parameter's value - value of field to set. Same
for other fields.
output
Optional parameter specifying the output format, one of: xml (default) or json.
Permissions Required
Edit permission for the Customer type.
Response
None
Example
Single create input example:
id=8330&companyName=API+Test+2&timeZone=EST
updateRecord
Purpose
Updates an existing data record from URL parameters.
Provide the integration names of the fields to set along with their values. If a field is not found, the system will
ignore that URL parameter. Fields values must be formatted the same way as you would for a CVS import,
see Importing data on page 622.
HTTP Method
PUT or POST
URL
https://www.rollbase.com/rest/api/updateRecord
1274 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Rollbase REST Methods
URL Parameters
sessionId
The session ID obtained from the body of the response when calling login on page 1246.
objName
The object integration name.
useIds
Boolean value. If true, use numeric IDs for lookup and picklist values; otherwise use integration
codes and record names.
field1, field2, ...
Integration name of the field(s) and their values. You must supply a value for required fields. Some
fields, such as those that represent relationships, can have multiple values. Use the field name only
once, and specify the ID of the records to attach separated with a | symbol.
output
Optional parameter specifying the output format, one of: xml (default) or json.
Permissions Required
Edit permission for the requested object type.
Response
Standard success or failure output.
Example
Input example (URL parameters):
&objName=person&id=314452&useIds=false&club_member=false&lastName=Smith&status=Created
Output example in JSON format:
{"status":"ok"}
Input example to update user record and send a welcome email (URL parameters):
&objName=user&output=json&id=138557&sendWelcomeEmail=true
Output example in JSON format:
{
"status": "ok",
"Msg": "1 fields have been processed."
}
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1275
Chapter 15: Reference
update2
Warning: This method is deprecated. Please change any existing code to use updateRecord on page
1274, which takes an object ID as a parameter.
Purpose
Updates an existing data record from URL parameters.
HTTP Method
POST or PUT
URL
https://www.rollbase.com/rest/api/update2
URL Parameters
sessionId
The session ID obtained from the body of the response when calling login on page 1246.
id
The record ID.
useIds
Boolean value. If true, use numeric IDs for lookup and picklist values; otherwise use integration
codes and record names.
field1
Parameter’s name – URL-encoded integration name of field to set; parameter’s value – URL-encoded
value of field to set.
field2
Same as field1 for other fields.
Names of URL parameters used by this API are integration names of your fields. If a field is not found, the
system ignores the URL parameter and keeps the current field's value. Fields' values must be formatted the
same way as CSV imported values; for more information, see Importing Data.
Permissions Required
Edit permission for the requested object type.
Response
Standard success or failure output.
1276 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Rollbase REST Methods
Example
Input example (URL parameters):
&id=314452&useIds=false&club_member=false&lastName=Smith&status=Created
Output example:
<resp status="ok">
<Msg>12 fields have been processed</Msg>
</resp>
authenticationProfile - Create
Purpose
This API creates an authentication profile.
Note: Not more than Password, Kerberos, Custom, API token & OE authentication profile can exist. This holds
true in case of creation of authentication profiles via API too. Authentication type cannot be created via APIs.
HTTP Method
POST
URL
https://www.rollbase.com/rest/api/authenticationProfile
URL Parameters
authType
The Type of authentication with which the profile has to be created.
authProfileName
Authentication profile name for the profile being created.
defaultUIAuth
This is an optional parameter. If set to true, the authentication profile which is being created will be
set as customers default authentication.
defaultAPIAuth
This is an optional parameter. If set to true, the authentication profile which is being created will be
set as customers default authentication.
Note: Remaining parameters are based on the type of authentication which ever is supported for
setAuthentication API currently.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1277
Chapter 15: Reference
Permissions Required
Full administrative privileges.
Response
The authentication profile for the tenant in XML or JSON format.
Sample XML output:
<?xml version="1.0" encoding="UTF-8" ?>
<resp status="ok">
<authProfileId>2a439049-f829-4b97-8ba1-575c131b0b8a</authProfileId>
<Msg>Authentication Profile has been created successfully</Msg>
</resp>
Sample JSON output:
{
"authProfileId": "54d72c32-a2e1-4cb7-a6fe-58e336e50ac8",
"Msg": "Authentication Profile has been created successfully"
}
authenticationProfile - Edit
Purpose
This API is used to edit an authentication profile by authentication profile ID.
HTTP Method
PUT
URL
https://www.rollbase.com/rest/api/authenticationProfile
URL Parameters
authProfileId
The authentication profile ID of the profile which has to be edited.
authProfileName
This is an optional parameter. Authentication profile name to update the existing authentication
profile.
defaultUIAuth
This is an optional parameter. If set to true, the authentication profile which is being created will be
set as customers default authentication.
defaultAPIAuth
This is an optional parameter. If set to true, the authentication profile which is being created will be
set as customers default authentication.
1278 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Rollbase REST Methods
Note: Remaining parameters are based on the type of authentication which ever is supported for
setAuthentication API currently.
Permissions Required
Full administrative privileges.
Response
The authentication profile for the tenant in XML or JSON format.
Sample XML output:
<?xml version="1.0" encoding="UTF-8" ?>
<resp status="ok">
<authProfileId>54d72c32-a2e1-4cb7-a6fe-58e336e50ac8</authProfileId>
<Msg>Authentication Profile has been updated successfully</Msg>
</resp>
Sample JSON output:
{
"authProfileId": "54d72c32-a2e1-4cb7-a6fe-58e336e50ac8",
"Msg": "Authentication Profile has been updated successfully"
}
Sample invalid responses
<?xml version="1.0" encoding="UTF-8" ?>
<resp status="fail">
<err>Authentication Profile with ID: 54d72cfd32-a2e1-4cb7-a6fe-58e336e50ac8 doesn't exist
or cannot be deleted</err>
</resp>
<?xml version="1.0" encoding="UTF-8" ?>
<resp status="fail">
<err>Global Authentications like Custom/Kerberos/API Token cannot be updated</err>
</resp>
<?xml version="1.0" encoding="UTF-8" ?>
<resp status="fail">
<err>This authentication type cannot be set as default API authentication</err>
</resp>
authenticationProfile - Delete
Purpose
This API is used to delete an authentication profile by an Authentication profile ID.
HTTP Method
DELETE
URL
https://www.rollbase.com/rest/api/authenticationProfile
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1279
Chapter 15: Reference
URL Parameters
authProfileId
The authentication profile ID of the profile which has to be deleted.
If an authentication profile is mapped to any role or if it set as a Default UI/API authentication profile
for a tenant, then we cannot delete the authentication profile.
Note: Global authentication profiles like Custom, Kerberos, API token cannot be deleted.
Permissions Required
Full administrative privileges.
Response
The authentication profile which is deleted for the tenant in XML format.
Sample XML output - valid response:
<?xml version="1.0" encoding="UTF-8" ?>
<resp status="ok">
<Msg>Authentication Profile with ID: 54d72c32-a2e1-4cb7-a6fe-58e336e50ac8 has been
deleted</Msg>
</resp>
Sample invalid responses
<?xml version="1.0" encoding="UTF-8" ?>
<resp status="fail">
<err>Authentication Profile with ID: 54d72cfd32-a2e1-4cb7-a6fe-58e336e50ac8 doesn't exist
or cannot be deleted</err>
</resp>
{
"status": "fail",
"message": "You cannot delete Custom/Kerberos/API token authentication profile"
}
getAllAuthenticationProfiles
Purpose
This API is used to return all authentication profiles list with each profile settings for viewing.
HTTP Method
GET
URL
https://www.rollbase.com/rest/api/getAllAuthenticationProfiles
Permissions Required
Full administrative privileges.
1280 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Rollbase REST Methods
Response
All authentication profiles for the tenant in XML or JSON format.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1281
Chapter 15: Reference
Sample XML output :
1282 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Rollbase REST Methods
<?xml version="1.0" encoding="UTF-8" ?>
<resp status="ok">
<authenticationProfiles>
<authenticationProfile>
<authProfileName>TEMPPROF</authProfileName>
<authProfileId>2af1f456-bc58-4c32-9ed4-7c6ffa7d54d4</authProfileId>
<authType>7</authType>
<authDescription>LDAP Advanced</authDescription>
<defaultUIAuth>false</defaultUIAuth>
<defaultAPIAuth>false</defaultAPIAuth>
<targetUrl>www.google.com</targetUrl>
<authenticationType>simple</authenticationType>
<searchCapabilities>Anonymous</searchCapabilities>
<userNameAttribute>uid</userNameAttribute>
<additionalParamKeys>[null]</additionalParamKeys>
<additionalParamValues>[null]</additionalParamValues>
</authenticationProfile>
<authenticationProfile>
<authProfileName>hi</authProfileName>
<authProfileId>2fe89a34-90ae-43f4-b46a-a6d26ee3ca4b</authProfileId>
<authType>7</authType>
<authDescription>LDAP Advanced</authDescription>
<defaultUIAuth>false</defaultUIAuth>
<defaultAPIAuth>false</defaultAPIAuth>
<targetUrl>ldap://your.org.com:port number</targetUrl>
<baseDistinguishedName>o=Progress Software Corporation</baseDistinguishedName>
<authenticationType>simple</authenticationType>
<searchCapabilities>Anonymous</searchCapabilities>
<userNameAttribute>uid</userNameAttribute>
<additionalParamKeys>[null]</additionalParamKeys>
<additionalParamValues>[null]</additionalParamValues>
</authenticationProfile>
<authenticationProfile>
<authProfileName>Password</authProfileName>
<authProfileId>6fba7e5a-64ab-47e8-ba4b-c360c482e280</authProfileId>
<authType>0</authType>
<authDescription>Password</authDescription>
<defaultUIAuth>true</defaultUIAuth>
<defaultAPIAuth>true</defaultAPIAuth>
<useSecQuestions>false</useSecQuestions>
<securityLevel>Low</securityLevel>
<expirPolicy>0</expirPolicy>
<enablePasswordHistory>false</enablePasswordHistory>
<passwordHistoryLimit>1</passwordHistoryLimit>
<passwordActivationContextExpiry>2</passwordActivationContextExpiry>
<newUserPasswordActivationContextExpiry>2</newUserPasswordActivationContextExpiry>
<useKnowledgeFactorToken>false</useKnowledgeFactorToken>
</authenticationProfile>
<authenticationProfile>
<authProfileName>hello</authProfileName>
<authProfileId>e952c42b-73da-4cd5-a01d-5fb289c6b22b</authProfileId>
<authType>7</authType>
<authDescription>LDAP Advanced</authDescription>
<defaultUIAuth>false</defaultUIAuth>
<defaultAPIAuth>false</defaultAPIAuth>
<targetUrl>www.google.com</targetUrl>
<authenticationType>simple</authenticationType>
<searchCapabilities>Anonymous</searchCapabilities>
<userNameAttribute>uid</userNameAttribute>
<additionalParamKeys>[null]</additionalParamKeys>
<additionalParamValues>[null]</additionalParamValues>
</authenticationProfile>
<authenticationProfile>
<authProfileName>TEMPPROF</authProfileName>
<authProfileId>82bff8d0-61aa-4348-bfab-c156fb89cc8c</authProfileId>
<authType>3</authType>
<authDescription>HTTP GET</authDescription>
<defaultUIAuth>false</defaultUIAuth>
<defaultAPIAuth>false</defaultAPIAuth>
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1283
Chapter 15: Reference
<targetURL>www.google.com</targetURL>
<headerKeys>[null,null,null,null,null]</headerKeys>
<headerValues>[null,null,null,null,null]</headerValues>
<responseText>Done</responseText>
</authenticationProfile>
<authenticationProfile>
<authProfileName>hello1</authProfileName>
<authProfileId>66b06b9d-907f-4a88-8dd2-28fde69fe219</authProfileId>
<authType>7</authType>
<authDescription>LDAP Advanced</authDescription>
<defaultUIAuth>false</defaultUIAuth>
<defaultAPIAuth>false</defaultAPIAuth>
<targetUrl>www.google.com</targetUrl>
<authenticationType>simple</authenticationType>
<searchCapabilities>Anonymous</searchCapabilities>
<userNameAttribute>uid</userNameAttribute>
<additionalParamKeys>[null]</additionalParamKeys>
<additionalParamValues>[null]</additionalParamValues>
</authenticationProfile>
<authenticationProfile>
<authProfileName>newldapADVANCED</authProfileName>
<authProfileId>711217f7-e2eb-4b1b-beb9-131177e410cb</authProfileId>
<authType>7</authType>
<authDescription>LDAP Advanced</authDescription>
<defaultUIAuth>false</defaultUIAuth>
<defaultAPIAuth>false</defaultAPIAuth>
<targetUrl>www.google.com</targetUrl>
<authenticationType>simple</authenticationType>
<searchCapabilities>Anonymous</searchCapabilities>
<userNameAttribute>uid</userNameAttribute>
<additionalParamKeys>[null]</additionalParamKeys>
<additionalParamValues>[null]</additionalParamValues>
</authenticationProfile>
<authenticationProfile>
<authProfileName>sdfsdfsd</authProfileName>
<authProfileId>50bd00f7-c863-4171-bcd9-d6b95cf75275</authProfileId>
<authType>6</authType>
<authDescription>OpenEdge</authDescription>
<defaultUIAuth>false</defaultUIAuth>
<defaultAPIAuth>false</defaultAPIAuth>
<useSecQuestions>false</useSecQuestions>
<realmURL>http://127.0.0.2/apsv</realmURL>
<realmClass>psc.stat.realm.oeuserrealm</realmClass>
<openEdgeDomain>oebpm</openEdgeDomain>
<openEdgeAccessCode>oebpm</openEdgeAccessCode>
<noHostVerify>false</noHostVerify>
<oeTokenUploadFileName>oespaclient.cp</oeTokenUploadFileName>
<oeCertUploadFileName>psccerts.jar</oeCertUploadFileName>
<managePassword>false</managePassword>
<certJarFileContent></certJarFileContent>
<tokenFileContent></tokenFileContent>
</authenticationProfile>
<authenticationProfile>
<authProfileName>TEMPPROF</authProfileName>
<authProfileId>2a439049-f829-4b97-8ba1-575c131b0b8a</authProfileId>
<authType>7</authType>
<authDescription>LDAP Advanced</authDescription>
<defaultUIAuth>false</defaultUIAuth>
<defaultAPIAuth>false</defaultAPIAuth>
<targetUrl>www.google.com</targetUrl>
<authenticationType>simple</authenticationType>
<searchCapabilities>Anonymous</searchCapabilities>
<userNameAttribute>uid</userNameAttribute>
<additionalParamKeys>[null]</additionalParamKeys>
<additionalParamValues>[null]</additionalParamValues>
</authenticationProfile>
<authenticationProfile>
<authProfileName>temp profile</authProfileName>
<authProfileId>0afa0e29-71c2-45a0-8d46-b79db5f13eb3</authProfileId>
1284 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Rollbase REST Methods
<authType>7</authType>
<authDescription>LDAP Advanced</authDescription>
<defaultUIAuth>false</defaultUIAuth>
<defaultAPIAuth>false</defaultAPIAuth>
<targetUrl>ldap://your.org.com:port number</targetUrl>
<baseDistinguishedName>o=yourCompanyName</baseDistinguishedName>
<authenticationType>simple</authenticationType>
<searchCapabilities>Anonymous</searchCapabilities>
<userNameAttribute>uid</userNameAttribute>
<additionalParamKeys>[null]</additionalParamKeys>
<additionalParamValues>[null]</additionalParamValues>
</authenticationProfile>
<authenticationProfile>
<authProfileName>abc</authProfileName>
<authProfileId>ebeb43e5-4503-4082-a568-21d613560f5d</authProfileId>
<authType>7</authType>
<authDescription>LDAP Advanced</authDescription>
<defaultUIAuth>false</defaultUIAuth>
<defaultAPIAuth>false</defaultAPIAuth>
<targetUrl>ehfukh</targetUrl>
<authenticationType>simple</authenticationType>
<searchCapabilities>Anonymous</searchCapabilities>
<userNameAttribute>uid</userNameAttribute>
<additionalParamKeys>[null]</additionalParamKeys>
<additionalParamValues>[null]</additionalParamValues>
</authenticationProfile>
<authenticationProfile>
<authProfileName>Custom</authProfileName>
<authProfileId>9aa9e22e-e7cb-4cbd-b8c8-c1209bcbe1c1</authProfileId>
<authType>7</authType>
<authDescription>LDAP Advanced</authDescription>
<defaultUIAuth>false</defaultUIAuth>
<defaultAPIAuth>false</defaultAPIAuth>
<targetUrl>www.google.com</targetUrl>
<authenticationType>simple</authenticationType>
<searchCapabilities>Anonymous</searchCapabilities>
<userNameAttribute>uid</userNameAttribute>
<additionalParamKeys>[null]</additionalParamKeys>
<additionalParamValues>[null]</additionalParamValues>
</authenticationProfile>
<authenticationProfile>
<authProfileName>TEMPPROF</authProfileName>
<authProfileId>e4af8f90-19ed-4c29-b940-a08d24e6abdd</authProfileId>
<authType>1</authType>
<authDescription>LDAP</authDescription>
<defaultUIAuth>false</defaultUIAuth>
<defaultAPIAuth>false</defaultAPIAuth>
<targetUrl>www.google.com</targetUrl>
<securityAuthentication>simple</securityAuthentication>
<securityPrincipal>CN={!loginName},OU=system,DC=example</securityPrincipal>
<securityCredential>{!password}</securityCredential>
<additionalParamKeys>[null]</additionalParamKeys>
<additionalParamValues>[null]</additionalParamValues>
</authenticationProfile>
<authenticationProfile>
<authProfileName>TEMPPROF</authProfileName>
<authProfileId>6bddbcb7-b565-4a57-8ae4-0323da8f0130</authProfileId>
<authType>2</authType>
<authDescription>HTTP POST</authDescription>
<defaultUIAuth>false</defaultUIAuth>
<defaultAPIAuth>false</defaultAPIAuth>
<targetURL>www.google.com</targetURL>
<headerKeys>["Content-Type",null,null,null,null,"text\u002Fxml;
charset=UTF-8"]</headerKeys>
<headerValues>[null,null,null,null]</headerValues>
<responseText>Done</responseText>
</authenticationProfile>
<authenticationProfile>
<authProfileName>dfgfgdfg</authProfileName>
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1285
Chapter 15: Reference
<authProfileId>b131ac73-3253-48d0-97e8-5d0105fa86bf</authProfileId>
<authType>7</authType>
<authDescription>LDAP Advanced</authDescription>
<defaultUIAuth>false</defaultUIAuth>
<defaultAPIAuth>false</defaultAPIAuth>
<targetUrl>ldap://your.org.com:port number</targetUrl>
<baseDistinguishedName>o=yourCompanyName</baseDistinguishedName>
<authenticationType>simple</authenticationType>
<searchCapabilities>Anonymous</searchCapabilities>
<userNameAttribute>uid</userNameAttribute>
<additionalParamKeys>[null]</additionalParamKeys>
<additionalParamValues>[null]</additionalParamValues>
</authenticationProfile>
<authenticationProfile>
<authProfileName>TEMPPROF</authProfileName>
<authProfileId>8916eb48-c1da-4a29-929e-4f9c801ae7a3</authProfileId>
<authType>1</authType>
<authDescription>LDAP</authDescription>
<defaultUIAuth>false</defaultUIAuth>
<defaultAPIAuth>false</defaultAPIAuth>
<targetUrl>www.google.com</targetUrl>
<securityAuthentication>simple</securityAuthentication>
<securityPrincipal>CN={!loginName},OU=system,DC=example</securityPrincipal>
<securityCredential>{!password}</securityCredential>
<additionalParamKeys>[null]</additionalParamKeys>
<additionalParamValues>[null]</additionalParamValues>
</authenticationProfile>
<authenticationProfile>
<authProfileName>Custom</authProfileName>
<authProfileId>Custom</authProfileId>
<authType>4</authType>
<authDescription>Custom</authDescription>
<defaultUIAuth>false</defaultUIAuth>
<defaultAPIAuth>false</defaultAPIAuth>
<Custom>customAuth2@476dc655</Custom>
</authenticationProfile>
<authenticationProfile>
<authProfileName>API Token</authProfileName>
<authProfileId>API Token</authProfileId>
<authType>10</authType>
<authDescription>API Token</authDescription>
<defaultUIAuth>false</defaultUIAuth>
<defaultAPIAuth>false</defaultAPIAuth>
</authenticationProfile>
</authenticationProfiles>
</resp>
1286 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Rollbase REST Methods
Sample JSON output
<?xml version="1.0" encoding="UTF-8" ?>
<resp status="fail">
<err>Authentication Profile with ID: 54d72cfd32-a2e1-4cb7-a6fe-58e336e50ac8 doesn't exist
or cannot be deleted</err>
</resp>
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1287
Chapter 15: Reference
{
"authenticationProfiles": [
{
"authProfileName": "temp ldap",
"authProfileId": "2af1f456-bc58-4c32-9ed4-7c6ffa7d54d4",
"authType": "7",
"authDescription": "LDAP Advanced",
"defaultUIAuth": "false",
"defaultAPIAuth": "false",
"targetUrl": "www.google.com",
"baseDistinguishedName": null,
"additionalUserDN": null,
"authenticationType": "simple",
"searchCapabilities": "Anonymous",
"userNameAttribute": "uid",
"additionalParamKeys": "[null]",
"additionalParamValues": "[null]"
},
{
"authProfileName": "ldap adv",
"authProfileId": "2fe89a34-90ae-43f4-b46a-a6d26ee3ca4b",
"authType": "7",
"authDescription": "LDAP Advanced",
"defaultUIAuth": "false",
"defaultAPIAuth": "false",
"targetUrl": "ldap://your.org.com:port number",
"baseDistinguishedName": "o=yourCompanyName",
"additionalUserDN": null,
"authenticationType": "simple",
"searchCapabilities": "Anonymous",
"userNameAttribute": "uid",
"additionalParamKeys": "[null]",
"additionalParamValues": "[null]"
},
{
"authProfileName": "Password",
"authProfileId": "6fba7e5a-64ab-47e8-ba4b-c360c482e280",
"authType": "0",
"authDescription": "Password",
"defaultUIAuth": "true",
"defaultAPIAuth": "true",
"useSecQuestions": "false",
"securityLevel": "Low",
"expirPolicy": "0",
"formula": null,
"enablePasswordHistory": "false",
"passwordHistoryLimit": "1",
"passwordActivationContextExpiry": "2",
"newUserPasswordActivationContextExpiry": "2",
"useKnowledgeFactorToken": "false",
"knowledgeFactorToken": null
},
{
"authProfileName": "temp",
"authProfileId": "e952c42b-73da-4cd5-a01d-5fb289c6b22b",
"authType": "7",
"authDescription": "LDAP Advanced",
"defaultUIAuth": "false",
"defaultAPIAuth": "false",
"targetUrl": "www.google.com",
"baseDistinguishedName": null,
"additionalUserDN": null,
"authenticationType": "simple",
"searchCapabilities": "Anonymous",
"userNameAttribute": "uid",
"additionalParamKeys": "[null]",
"additionalParamValues": "[null]"
},
{
1288 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Rollbase REST Methods
"authProfileName": "TEMPPROF",
"authProfileId": "82bff8d0-61aa-4348-bfab-c156fb89cc8c",
"authType": "3",
"authDescription": "HTTP GET",
"defaultUIAuth": "false",
"defaultAPIAuth": "false",
"targetURL": "www.google.com",
"headerKeys": "[null,null,null,null,null]",
"headerValues": "[null,null,null,null,null]",
"responseText": "Done"
},
{
"authProfileName": "hello1",
"authProfileId": "66b06b9d-907f-4a88-8dd2-28fde69fe219",
"authType": "7",
"authDescription": "LDAP Advanced",
"defaultUIAuth": "false",
"defaultAPIAuth": "false",
"targetUrl": "www.google.com",
"baseDistinguishedName": null,
"additionalUserDN": null,
"authenticationType": "simple",
"searchCapabilities": "Anonymous",
"userNameAttribute": "uid",
"additionalParamKeys": "[null]",
"additionalParamValues": "[null]"
},
{
"authProfileName": "newldapADVANCED",
"authProfileId": "711217f7-e2eb-4b1b-beb9-131177e410cb",
"authType": "7",
"authDescription": "LDAP Advanced",
"defaultUIAuth": "false",
"defaultAPIAuth": "false",
"targetUrl": "www.google.com",
"baseDistinguishedName": null,
"additionalUserDN": null,
"authenticationType": "simple",
"searchCapabilities": "Anonymous",
"userNameAttribute": "uid",
"additionalParamKeys": "[null]",
"additionalParamValues": "[null]"
},
{
"authProfileName": "sdfsdfsd",
"authProfileId": "50bd00f7-c863-4171-bcd9-d6b95cf75275",
"authType": "6",
"authDescription": "OpenEdge",
"defaultUIAuth": "false",
"defaultAPIAuth": "false",
"useSecQuestions": "false",
"realmURL": "http://172.16.23.212:8093/apsv",
"realmClass": "psc.stat.realm.oeuserrealm",
"openEdgeDomain": "oebpm",
"openEdgeAccessCode": "oebpm",
"noHostVerify": "false",
"oeTokenUploadFileName": "oespaclient.cp",
"oeCertUploadFileName": "psccerts.jar",
"managePassword": "false",
"suLoginname": "",
"suPassword": "",
"guestLoginname": "",
"guestPassword": "",
"certJarFileContent": "",
"tokenFileContent": ""
},
{
"authProfileName": "TEMPPROF",
"authProfileId": "2a439049-f829-4b97-8ba1-575c131b0b8a",
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1289
Chapter 15: Reference
"authType": "7",
"authDescription": "LDAP Advanced",
"defaultUIAuth": "false",
"defaultAPIAuth": "false",
"targetUrl": "www.google.com",
"baseDistinguishedName": null,
"additionalUserDN": null,
"authenticationType": "simple",
"searchCapabilities": "Anonymous",
"userNameAttribute": "uid",
"additionalParamKeys": "[null]",
"additionalParamValues": "[null]"
},
{
"authProfileName": "templink",
"authProfileId": "0afa0e29-71c2-45a0-8d46-b79db5f13eb3",
"authType": "7",
"authDescription": "LDAP Advanced",
"defaultUIAuth": "false",
"defaultAPIAuth": "false",
"targetUrl": "ldap://your.org.com:portnumber",
"baseDistinguishedName": "o=yourCompanyName",
"additionalUserDN": null,
"authenticationType": "simple",
"searchCapabilities": "Anonymous",
"userNameAttribute": "uid",
"additionalParamKeys": "[null]",
"additionalParamValues": "[null]"
},
{
"authProfileName": "abc",
"authProfileId": "ebeb43e5-4503-4082-a568-21d613560f5d",
"authType": "7",
"authDescription": "LDAP Advanced",
"defaultUIAuth": "false",
"defaultAPIAuth": "false",
"targetUrl": "ehfukh",
"baseDistinguishedName": null,
"additionalUserDN": null,
"authenticationType": "simple",
"searchCapabilities": "Anonymous",
"userNameAttribute": "uid",
"additionalParamKeys": "[null]",
"additionalParamValues": "[null]"
},
{
"authProfileName": "Custom",
"authProfileId": "9aa9e22e-e7cb-4cbd-b8c8-c1209bcbe1c1",
"authType": "7",
"authDescription": "LDAP Advanced",
"defaultUIAuth": "false",
"defaultAPIAuth": "false",
"targetUrl": "www.google.com",
"baseDistinguishedName": null,
"additionalUserDN": null,
"authenticationType": "simple",
"searchCapabilities": "Anonymous",
"userNameAttribute": "uid",
"additionalParamKeys": "[null]",
"additionalParamValues": "[null]"
},
{
"authProfileName": "TEMPPROF",
"authProfileId": "e4af8f90-19ed-4c29-b940-a08d24e6abdd",
"authType": "1",
"authDescription": "LDAP",
"defaultUIAuth": "false",
"defaultAPIAuth": "false",
"targetUrl": "www.google.com",
1290 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Rollbase REST Methods
"securityAuthentication": "simple",
"securityPrincipal": "CN={!loginName},OU=system,DC=example",
"securityCredential": "{!password}",
"additionalParamKeys": "[null]",
"additionalParamValues": "[null]"
},
{
"authProfileName": "TEMPPROF",
"authProfileId": "6bddbcb7-b565-4a57-8ae4-0323da8f0130",
"authType": "2",
"authDescription": "HTTP POST",
"defaultUIAuth": "false",
"defaultAPIAuth": "false",
"targetURL": "www.google.com",
"httpBody": null,
"headerKeys": "[\"Content-Type\",null,null,null,null,\"text\\u002Fxml; charset=UTF-8\"]",
"headerValues": "[null,null,null,null]",
"responseText": "Done"
},
{
"authProfileName": "TEMPPROF",
"authProfileId": "8916eb48-c1da-4a29-929e-4f9c801ae7a3",
"authType": "1",
"authDescription": "LDAP",
"defaultUIAuth": "false",
"defaultAPIAuth": "false",
"targetUrl": "www.google.com",
"securityAuthentication": "simple",
"securityPrincipal": "CN={!loginName},OU=system,DC=example",
"securityCredential": "{!password}",
"additionalParamKeys": "[null]",
"additionalParamValues": "[null]"
},
{
"authProfileName": "Custom",
"authProfileId": "Custom",
"authType": "4",
"authDescription": "Custom",
"defaultUIAuth": "false",
"defaultAPIAuth": "false",
"Custom": "customAuth2@f4ed27"
},
{
"authProfileName": "API Token",
"authProfileId": "API Token",
"authType": "10",
"authDescription": "API Token",
"defaultUIAuth": "false",
"defaultAPIAuth": "false"
}
]
}
getAuthenticationProfileById
Purpose
This API will return settings of an authentication profile based on the given authentication profile ID for viewing.
HTTP Method
GET
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1291
Chapter 15: Reference
URL
https://www.rollbase.com/rest/api/getAuthenticationProfileById
URL Parameters
authProfileId
The authentication profile ID of the profile which has to be edited.
Permissions Required
Full administrative privileges.
Response
The authentication profile by Id for the tenant in XML format.
Sample XML output:
<?xml version="1.0" encoding="UTF-8" ?>
<resp status="ok">
<authenticationProfile>
<authProfileName>TEMPPROF</authProfileName>
<authProfileId>6bddbcb7-b565-4a57-8ae4-0323da8f0130</authProfileId>
<authType>2</authType>
<authDescription>HTTP POST</authDescription>
<defaultUIAuth>false</defaultUIAuth>
<defaultAPIAuth>false</defaultAPIAuth>
<targetURL>www.google.com</targetURL>
<headerKeys>["Content-Type",null,null,null,null,"text\u002Fxml;
charset=UTF-8"]</headerKeys>
<headerValues>[null,null,null,null]</headerValues>
<responseText>Done</responseText>
</authenticationProfile>
</resp>
Sample invalid responses
{
"status": "fail",
"message": "Authentication profile with id: 6bddbcb7-b565-4a57-8sdfdfae4-0323da8f0130
does not exist"
}
mapAuthenticationToRole
Purpose
This API is used to map UI authentication & API authentication to certain roles.
HTTP Method
POST
URL
https://www.rollbase.com/rest/api/mapAuthenticationToRole
1292 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Rollbase CSS Styles for the Classic UI
URL Parameters
roles
The role id's list as "," separated parameter.
UIAuthProfileId
This is the authentication profile ID to which UI authentication of above roles is to be mapped.
APIAuthProfileId
This is the authentication profile ID to which API authentication of above roles is to be mapped.
Permissions Required
Full administrative privileges.
Response
The authentication profile mapped to roles for the tenant in JSON format.
Sample JSON output:
{
"Msg": "Role(s) [90, 35011] are mapped to respective Authentication profiles",
"UIAuthProfileId": "6fba7e5a-64ab-47e8-ba4b-c360c482e280",
"APIAuthProfileId": "6fba7e5a-64ab-47e8-ba4b-c360c482e280"
}
Sample invalid responses
{
"status": "fail",
"message": "You have passed atleast one non-numeric input in roles parameter"
}
{
"status": "fail",
"message": "Authentication Profile with ID: 6fba7e5a-64ab-47e8-sdfba4b-c360c482e280 does
not exist"
}
Rollbase CSS Styles for the Classic UI
The topics in this section describe the HTML styles used by Rollbase Cascading Style Sheets (CSSs) in the
Classic UI.
Table Styles
The following classes define Rollbase table styles.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1293
Chapter 15: Reference
CSS Class Name Description
rbs_breadcrumbs Renders the table that has the setup breadcrumbs link
(print | Edit Page Layout)
rbs_componentContentTable Renders the table that contains all the components in
the component pages.
rbs_detailTable Renders a wide table that displays details of
components.(the tds inherit detailHTMLCol style)
rbs_editorFormTable Renders the form table in page editor for portal pages
rbs_errormsgTable Renders the error message table
rbs_fieldBottomColumn Renders a column that fills the entire row and has
bottom border (AssignPages.jsp)
rbs_helptipTable Renders the help tip table with yellow background
rbs_highlightTable Renders a table with the background color set to
highlight color
rbs_lightRedTable Renders a table with light red background used in
displaying error messaged
rbs_lightsilverTable Renders a table that has light silver background
rbs_listTable Renders the table that contains list views
rbs_lookupValue Renders the table that holds the lookup values
rbs_mainContentTable Renders the table that has all the contents in a page,
sidebar and other contents
rbs_mediumPurpleTable Renders a table with medium purple background used
in report pages.
rbs_miniCalTable Renders the mini-calendar table
rbs_notificationTable Renders the notification table in page Editor pages.
rbs_outerMainComponentTable Renders the outer table that contains the component
content in component setup pages
rbs_primaryTableNoborder Renders the table with background color set to primary
color with no borders
rbs_primaryWideTable Renders a table with background color set to primary
color that is wide and has a left border
rbs_roundedTable Renders the blank rows in a section in primary color
1294 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Rollbase CSS Styles for the Classic UI
CSS Class Name Description
rbs_secondaryWide Renders a table with the background color set to
secondary color
rbs_setupPageInnerTable Renders the inner table in component setup pages.
rbs_setupPageOuterTable Renders the outer table in component setup pages.
rbs_silverSideBorderTable Renders a table with silver side borders.
rbs_silverTableWide Renders a table with background color set to silver
color with 100% width.
rbs_whiteBlankTable Renders a blank table with white background
rbs_widePrimary Renders a table with background color set to primary
color that is wide and has a left border and right
primary color borders
rbs_wideSilverEmptyTable Renders a table with background color set to silver
color with border bottom
rbs_wideTable Renders a table that is wide and has no borders.
Table Cell Styles
The following Rollbase CSS classes define the appearance of table cells.
CSS Class Description
rbs_centerwide Renders a column that is center aligned
rbs_InfoSmallWide Renders detailed information that describes various
features e.g., filters expression info. This style Renders
info in small size and is used as column style
rbs_PageTopicWide Renders the topic of the page in component setup
pages (Object: Portal: etc)
rbs_recordActionCol Render record action column (edit, delete button etc)
rbs_reportExpand Render expanding column in report
rbs_rightWide Render column wide and right
rbs_shortColFieldbottom Renders short column with bottom border
rbs_silverbottom Renders column with silver bottom border
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1295
Chapter 15: Reference
CSS Class Description
rbs_thinSectionTitle Renders the column that displays the thin section's
title
rbs_warningIconCol Renders the column that display warning icon in dialog
box pages
rbs_wideLeftTop Render column wide and left and top (Components.jsp)
td.rbs_boldDataCol Render columns that have information that is bold
(relationsEdit, relationshipConvert pages)
td.rbs_detailHTMLCol Renders a column with detail information about the
component property in Setup Page
td.rbs_disabledFieldProp Renders html that displays disabled field properties in
field create/Edit pages.
td.rbs_emailLeftDataCol Renders column in 2 column layout pages that has the
field input controls in email pages. This style is more
prominently used in Email sending pages
td.rbs_errorDataCol Renders an error column in a 2 column layout pages
that has the field input controls that are not required.
This style is more prominently used in Component
setup pages and in record pages.
td.rbs_errorDataColWide Renders an error column in single column layout pages
that has the field input controls that are not required.
This style is more prominently used in Component
setup pages and in record pages.
td.rbs_errorLabelRequired Renders an error column in a 2 column layout pages
that has the field labels that are required. This style is
more prominently used in Component setup pages
and in record pages.
td.rbs_errorLabelRequired Wide Renders an error column in a single column
layout pages that has the field labels that are required.
This style is more prominently used in Component
setup pages and in record pages.
td.rbs_errorLabelRight Renders error column in a 2 column layout pages that
has the field labels that are not required. This style is
more prominently used in Component setup pages
and in record pages.
td.rbs_errorLabelRightWide Renders error column in a single column layout pages
that has the field labels that are not required. This style
is more prominently used in Component setup pages
and in record pages.
1296 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Rollbase CSS Styles for the Classic UI
CSS Class Description
td.rbs_filtersTable Renders the filters table in search, view, report and
chart pages.
td.rbs_grayDetailHTMLcol Renders a column with detail information about the
component property in Setup Page
td.rbs_grayDetailInfoCol Renders the help information about the component in
detail in gray in setup pages
td.rbs_leftDataCol Renders column in a 2 column layout pages that has
the field input controls that are not required. This style
is more prominently used in Component setup pages
and in record pages.
td.rbs_leftDataColWide Renders column in single column layout pages that
has the field input controls that are not required. This
style is more prominently used in Component setup
pages and in record pages.
td.rbs_listItemValueRight Renders the right column that displays the total
summary of lists.
td.rbs_listSummaryNumber Renders the column that shows the totals of grouped
list items in list views. Displays the number.
td.rbs_listSummaryText Renders the left column that displays the total
summary of lists.
td.rbs_propertiesEditorRightCol Renders the right column that displays component
properties in page editor page.
td.rbs_rightLabel Renders column in a 2 column layout pages that has
the field labels that are not required. This style is more
prominently used in Component setup pages and in
record pages.
td.rbs_rightLabelRequired Renders column in a 2 column layout pages that has
the field labels that are required. This style is more
prominently used in Component setup pages and in
record pages.
td.rbs_rightLabelWide Renders column in a single column layout pages that
has the field labels that are not required. This style is
more prominently used in Component setup pages
and in record pages.
td.rbs_rightWideLabelRequired Renders column in a single column layout pages that
has the field labels that are required. This style is more
prominently used in Component setup pages and in
record pages.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1297
Chapter 15: Reference
CSS Class Description
td.rbs_SetupColumnRequired Renders an empty column in a two column layout
pages. This style is more prominently used in
component Setup pages.
td.rbs_SetupDataColWide Renders a column in single column layout pages that
has the field input controls in component setup pages.
This style is more prominently used in Component
setup pages and in record pages.
td.rbs_SetupLabelNoFieldBottom Renders column in a two column layout pages where
the column needs no bottom border. This style is more
prominently used in component Setup pages.
td.rbs_silverCol Renders a column that has white borders. Used in
component setup pages.
td.rbs_summaryNumberCol Renders the right column that displays the group
summary of lists.
td.rbs_summaryTextCol Renders the left column that displays the group
summary of lists.
Table Row Styles
The following CSS classes define Rollbase table row styles.
CSS Class Description
rbs_parentRow Renders a list Item that is a parent row for other items.
This row has the group name for the list Items. Other
styles that must inherit this style are td.listItemValue,
td. smallIcon, td.actonCol, td.groupSpacer,
td.checkbox, td.listItemNumberValue, td.summary,
td.totalSummary, td.rbs_listItemValueRight. these
define the individual styles of column within this row.
rbs_rowHighlightUnviewed Renders a row to render a list Item that is currently not
being viewed. Other styles that must inherit this style
are td.listItemValue, td. smallIcon, td.actonCol,
td.groupSpacer, td.checkbox, td.listItemNumberValue,
td.summary, td.totalSummary,
td.rbs_listItemValueRight. these define the individual
styles of column within this row.
1298 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Rollbase CSS Styles for the Classic UI
CSS Class Description
rbs_rowHighlightViewed Renders a row to render a list Item that is currently
being viewed. Other styles that must inherit this style
are td.listItemValue, td. smallIcon, td.actonCol,
td.groupSpacer, td.checkbox, td.listItemNumberValue,
td.summary, td.totalSummary,
td.rbs_listItemValueRight. these define the individual
styles of column within this row.
rbs_rowUnviewed Renders a row to render a list Item that has not been
viewed yet. Other styles that must inherit this style are
td.listItemValue, td. smallIcon, td.actonCol,
td.groupSpacer, td.checkbox, td.listItemNumberValue,
td.summary, td.totalSummary,
td.rbs_listItemValueRight. these define the individual
styles of column within this row.
rbs_rowViewed Renders a row to render a list Item that has been
viewed previously. Other styles that must inherit this
style are td.listItemValue, td. smallIcon, td.actonCol,
td.groupSpacer, td.checkbox, td.listItemNumberValue,
td.summary, td.totalSummary,
td.rbs_listItemValueRight. these define the individual
styles of column within this row.
rbs_whiteListItem Renders a white row to render a list Item that has not
been viewed yet. Other styles that must inherit this
style are td.listItemValue, td. smallIcon, td.actonCol,
td.groupSpacer, td.checkbox, td.listItemNumberValue,
td.summary, td.totalSummary,
td.rbs_listItemValueRight. these define the individual
styles of column within this row.
Text Styles
the following CSS classes define Rollbase text styles.
CSS Class Description
Renders the components header info "Red= required
rbs_ComponetHeaderInfo information"
rbs_alertMsg Renders text that display error messages or alerts
rbs_centerBold Renders text center aligned and bold
rbs_graybold Renders bold gray text (numbers in filters)
rbs_InfoGrayBoldWide Renders detailed information that describes various
features e.g., filters expression info. This style Renders
info in that is gray and bold.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1299
Chapter 15: Reference
CSS Class Description
rbs_infoMessage Renders the messages in #FFF1A8 color
rbs_InfoSmallWide Renders detailed information that describes various
features e.g., filters expression info. This style Renders
info in small size and is used as column style
rbs_largeCourier Renders text large and courier font
rbs_miniCalHeader Renders Month and year text in calendar
rbs_rightLargeText Renders text that is large and right aligned
rbs_selectedButton Renders a div with #FFF8CE color
rbs_silverBold Renders the text in silver and bold and center. used
in rendering the relation type names
rbs_smallGray Renders text that is small in size and is gray
rbs_smallInfoGrayBold Renders detailed information that describes various
features e.g., filters expression info. This style Renders
info in gray and small size and is bold
rbs_smallSpacer Renders spacer column (lists)
rbs_smallStatus Renders silver text very small
rbs_unselectedButton Renders a div with gray color
rbs_xxlargeAlert Renders a very large text as alert (used in
confirmcheckDialog.jsp)
Page Editor Styles
The following CSS classes define the style of Rollbase Page Editor.
rbs_AvailCompName Renders the text that displays the available component
names in page editor.
rbs_componentName Renders component name in page editor
rbs_loginFormFields Render the login form mockup in page editor
rbs_peDivSpacer Renders a spacer div in page editor
rbs_peloginTable Renders the mockup login table in page editor for login
pages
1300 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Rollbase CSS Styles for the Classic UI
rbs_propertiesEditorLeftCol Renders the left column of properties table in page
Editor
rbs_scriptComponent Renders the container that has script component in
page editor
rbs_readOnly Renders the text read only
Link Styles
The following CSS classes define Rollbase link styles.
CSS Class Description
rbs_BacktoCol Renders the Back to List links
rbs_BoldNavyLink Render a bold link in navy color (used to display the
portal main link)
rbs_calNext Renders month navigation links in mini calendar
rbs_highlightLinks Renders columns that are highlighted yellow
rbs_NewComponentLink Renders the new component link (New Object, New
Template etc) in component pages(objects.jsp, tabs.jsp
etc) in Setup Pages
rbs_ReturnToAppLink Renders the link "return to <appname> application" in
Object definition page
rbs_viewSectionLinks Renders links in a section like in Edit View
rbs_wideSectionLinks Renders links in a section and fills the entire row like
Edit Chart Link.
Sidebar Styles
The following CSS classes define Rollbase sidebar styles.
CSS Class Description
rbs_sidebarContent Renders the column that has the entire sidebar content
rbs_sidebarLink Render links in side bar
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1301
Chapter 15: Reference
Field types
The topics in this section describe field types.
Text field
The Text field type can contain any combination of characters. You can optionally define the following properties:
• Default Size — The default size of the input field shown in forms (you can override this default as a page-level
property using the page editor)
• Length — The maximum allowed length (number of characters)
• This field allows storing multiple values for supported languages — Check if this field allows multiple
values for supported languages (for customers with more than one language assigned; see Language
support on page 740)
• Input Mask — Allows you to place restrictions on the type and format of data entered in the field. The input
mask is applied during input on new, edit, and quick create pages. The input mask can include:
• The # symbol for numeric character
• The * symbol for any input character
• Letters and separators
For example, the input mask for a phone number might look like this: (###)###-####
Note: Input masks are not applied during inline editing on a record list page. Disabling inline editing for a
field with an input mask can prevent users from entering invalid data. See Advanced field properties on
page 1319 for information about enabling and disabling inline editing. See Inline editing on page 448 for
information about inline editing.
Note: The maximum allowed length cannot exceed 100 characters. However this limitation does not apply to
external databases. See Using external tables as Rollbase objects on page 615 for more information.
Text Area Field
With the Text Area Field type, Users can enter multiple lines of text. You can optionally define the following
properties:
• A maximum length of input (number of characters) to accept.
• Default height and width of HTML text area (you can override this default as a Page-level property using
the Page Editor).
• Enable a Rich Text Editor so users can enter text as formatted HTML.
Note: The length of text stored in Text Area cannot exceed 80,000 characters.
Text Area field type does not support filtering.
1302 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Field types
Checkbox Field
With the Checkbox Field type, users can select a Checked (true) or Unchecked (false) value. When creating
a Checkbox Field, you specify:
• >Whether you want to the Field to be checked or unchecked by default.
• An optional checkbox for hiding the display label for this Field on UI Pages.
• Additional text to be rendered on the right of checkbox.
Note: If Checkbox is marked as "required" it must be checked in input form, otherwise it will cause a validation
error. This feature is rarely used except for some legal applications.
Decimal field
With the Decimal field type, users can enter any number with decimals. You can optionally define the following
properties:
• Number of decimal places to display to the right of the decimal point.
• Number to be used as the default value for new records.
• Minimum and maximum allowed values.
See Configuring Integer and Decimal field formats on page 136 for information about formatting Decimal fields.
Currency field
With the Currency field type, users can enter a dollar or other currency amount. You can optionally define the
following properties:
• Currency Format (this setting will only affect formatting of the field). See Currency formats on page 732 for
supported currency formats.
• Default value for new records.
• Minimum allowed value for this field.
• Maximum allowed value for this field.
Note: On Edit pages, Rollbase adds an HTML DOM handler to automatically format the value of a Currency
field (according to the selected format) when an input field loses focus.
When you create a new Currency field for objects that support the multi-currency attribute, you can optionally
create a counterpart Base Currency field that will transfer the foreign currency amount into the currency of your
bookkeeping.
Note: Due to database limitations, Currency and Decimal fields cannot hold values larger than
100,000,000,000.0
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1303
Chapter 15: Reference
Base Currency field
This field is only available for objects that support the Multi-Currency attribute. The Base Currency field is a
dependent field that transfers the foreign currency amount specified in the selected Currency field (see above)
into the currency of your bookkeeping. You can create this field as a counterpart for new a Currency field. To
create a Base Currency field from scratch, specify the following:
• The Currency Field that holds the original amount in foreign currency.
• The Base Currency to transfer to (typically currency of your bookkeeping).
See Multi-currency support on page 349 for more info on multi-currency support in Rollbase.
Date Field
With the Date Field type, users can enter a date or pick a date from a calendar popup. You can optionally
define the following properties:
• Whether you want to us the date format or long date format on application pages. See Configuring Date
and Date/Time field formats on page 136 for more information.
• Whether you want to use the current date, or the current date plus or minus several days, as the default
creation date for new records.
• Whether you want to use the current date, or the current date plus or minus several days, as the default
update date for changed records.
Date/Time field
With the Date/Time field, users can enter a date and a time, or pick a date from a calendar popup. When the
user selects a date from the calendar popup, Rollbase enters that date and the current time into the Date/Time
field.
When you create a date/time field, you can specify whether you want to format the value as full text or as an
abbreviation and whether you want the field to be automatically populated in specified situations. See Configuring
Date and Date/Time field formats on page 136 for more information.
Time field
With the Time field type, users can enter the time (hours and minutes). This field does not provide any
type-specific settings. Time fields are formatted on application pages according to the time format selected for
a user on the My Localization Settings on page 715.
1304 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Field types
Email Field
With the Email Field type, users can enter an email address that is server-side validated to ensure it is in a
valid email format.
You can optionally define a maximum length for the email address.
Phone Number field
With the Phone Number field type, users can enter a phone number which will be automatically formatted
according to specified input mask, such as ###-###-#### The input mask is applied during input on new, edit,
and quick create pages. The input mask can include:
• The # symbol for numeric character
• The * symbol for any input character
• Letters and separators
Note: Rollbase now provides the Click to Call feature for Rollbase applications on your desktop and mobile
devices. Any phone number will automatically appear as a clickable link enabling users to quick dial the number
from the UI.
Password Field
With the Password Field type, users can enter and securely store passwords for authentication of Portal Users
or for any other purpose, such as integration with third-party systems. You can optionally define the following
properties:
• Minimum length (number of characters) password may have.
• Check if password must contain both letters and digits.
For security reasons passwords are encrypted when stored internally. Actual password's value is never displayed
on UI pages. The decision to display password’s value at AJAX, REST, or SOAP is governed through the View
Integration Password permission. The password's value is always accessible through formulas and Server
Side API’s. See Roles and permissions on page 648 for more information.
When user is entering password on New Record or Edit page he/she is required to confirm entered value by
re-typing it again in text box below. If password is already stored in the system it is not populated in text boxes
for security reasons. Instead there is a note "Password on file" below text boxes. Provide a new value to override
password on file. Use "Remove" link to clear password's value without providing a new value.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1305
Chapter 15: Reference
Integer field
With the Integer field type, users can enter any number (without decimals). This field offers the same settings
(min value, max value, default value) as other numeric input fields.
See Configuring Integer and Decimal field formats on page 136 for information about formatting Integer fields.
Percent Field
With the Percent Field type, users can enter a percentage (number including decimals) and a % sign is
automatically added. You can optionally define a maximum number of decimal places.
Picklist Field
The Picklist field type allows users to select a value from a list you define. Several other field types (multi-select
picklists, radio buttons and group of checkboxes) have a similar configuration.
Creating a picklist
First, define a list of values, one value per line, for the picklist. Each value represents a selectable item. The
length of a picklist value cannot exceed 100 characters. If you want a particular value to be selected by default
for new records, prefix it with {D}. Optionally, at the end of each line, add | followed by an integration name for
that value (no longer than 40 characters). Formulas and APIs can use this integration name to access unique
picklist values (e.g., for data import and export).
Example: In the following list of picklist values, each value is assigned an integration name and Yes is the
default value:
You can also choose whether to display values sorted alphabetically (the default) or in the order the values
were entered.
1306 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Field types
Sharing a picklist
In some situations, you might want picklists belonging to different objects to have the same set of values.
Rollbase allows you to share picklists among those objects. To share a picklist, select Share as New from the
Shared As drop-down when you create the picklist.
To use values from an existing shared picklist, select the integration name of the shared picklist from the Shared
As drop-down when you create the picklist. The content of the Values box is replaced with existing values
from the selected shared picklist.
Editing picklists
The following rules and behaviors apply when editing picklists:
• You cannot change the integration name of a shared picklist. All picklists that share the same values have
the same integration name.
• Changing the text value of a picklist item destroys the modified item and creates a new item. Existing records
will lose their assigned values. If you just want to change the text of a picklist item, use the Replace
functionality as described in Replacing a picklist value on page 139.
• If you delete the text value of a picklist item, existing records will lose their assigned values.
• Shared picklists share the same text values for their picklist items. If you delete the text value from one
shared picklist, that value is deleted from all of the picklists that share with it.
Picklist Multiselect
With the Picklist (Multi-Select) Field type, users can select any number of values from a list of values you define.
You define Multi-select picklists in the same way as single-select picklists, with two additional optional capabilities:
• You can mark more than one value as a default value with the {D} prefix.
• You can choose a height (in rows) to determine the number of values visible at any given time. If more than
one value is visible the user can use the CTRL key plus their mouse to select multiple items.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1307
Chapter 15: Reference
Radio Button Field
With the Radio Button Field type, users can select a single choice from a group of radio buttons. You define
Radio Buttons in the same manner as picklists, with an additional layout setting: Alignment that determines
whether to align the Radio Buttons vertically or horizontally.
Group Checkbox Field
With the Group of Checkboxes Field type, users can select any number of checkboxes in a group. You define
in the same manner as Multi-Select Picklist Fields are defined with an additional layout setting: Alignment that
determines whether to align the Group of Checkboxes vertically or horizontally.
URL Field
With the URL Field type, Users can enter any website address and the URL is displayed as an HTML link. The
content of that link will be displayed in a new browser window.
Tip: You can specify "Link Text" to be used as the text representation of this URL. If link text is not specified
the URL itself (possibly truncated with ellipses) will be used.
Auto-number Field
The Auto-number field type is an automatically generated sequential number or code that uses a display format
you define. When you define a start number using a specific display format, the start number is used to initialize
the auto-number sequence.
An Auto-number format may include year, month and day. When you create an auto-number field, you must
specify:
• A display format (mandatory) defined by a template. Syntax and examples are presented inline while creating
the field.
• A starting number (mandatory) for the sequence number portion.
• An option allowing you to assign auto-numbers to all existing Object records once this field is created or
updated.
• By default, Auto-number fields do not allow duplicate values.
1308 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Field types
The current number indicates a start number that is currently in use to initialize the auto-number sequence.
Editing the current number is a separate action. When you update or edit a Current Number:
• Preferably, provide a value that is greater than the existing current number.
• If you choose to specify a lower current number value, check for any existing records for the selected object,
and if available, delete all those records from the object and the Recycle Bin.
Note:
• Auto-Number fields are read-only and display the text "Auto-generated" when creating a new record.
However, you can edit the value of this field on its edit page.
• New number for Auto-Number field is assigned when user saves a new record.
• An auto-number sequence is updated only for a valid format.
Tip: Auto-Number fields are often used in the Object definition name templates.
Existing Rollbase users may see Auto-number Functional Changes for more information.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1309
Chapter 15: Reference
Auto-number Functional Changes
1310 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Field types
Here's a description of the functional changes applied to the Auto-number field behavior.
Functionality Prior to Version 5.0 Behavior from 5.0 onward
Starting • In the Field XML Definition, • The Starting number is used to initialize the auto-number
number the field property was - sequence. Once initiated, the auto-number sequence is
autoNumstart known as the Current Number.
• When installing a new • In the Field XML Definition, the field property
application or cloning an “autoNumStart” is replaced with “startingAutoNumber”.
object definition, the
auto-number sequence
• When installing a new application or cloning an object
definition the auto-number sequence starts with the
always starts from 1.
Starting number.
Current This property did not exist. • The current number can be set to any value greater than
Number Instead, the starting number the current value.
displayed the current running
sequence of the auto-number • If you choose to specify a lower current number value,
field. check for any existing records for the selected object. If
records are available, delete all those records from the
object and the Recycle Bin.
• This property is displayed only when you are editing the
auto-number field.
• Editing a current number is a separate action performed
in the Edit Current Number dialog which updates the
current number when you save it.
Note: The value of a current number cannot be edited or
retrieved through APIs .
• Field • Field level validations are When a record is being created from the user interface,
Definition executed for records. there is no validation involved as the auto-number field is
Level empty until the record is created.
Validations
• All triggers used to consume
the auto-number field value.
• Triggers Note: When creating a record from the user interface, if
(before there are null or blank check applied on the auto-number
create field, the validation triggers might fail due to which the script
action) might need modification. Other triggers consume the
auto-number field value.
Create records The auto-number field behavior The auto-number behavior is similar whether you are
for creating records from the creating records from the user interface or the APIs.
user interface and the APIs were
different. • Displays the text, " Auto-generated" in the user interface.
Rollbase generates a value for the auto-number field
when the record is saved.
• Rollbase generates a value for the auto-number field, if
the value is not specified in the API.
Edit records The auto-number field behavior The auto-number field behavior is similar when editing
for editing records from the user records from the user interface and APIs. In both the cases,
interface and the APIs were the current number is updated only if the auto-number field
different. value is set in a valid format.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1311
Chapter 15: Reference
Functionality Prior to Version 5.0 Behavior from 5.0 onward
Cloning Rollbase always generates a new value for the auto-number
records fields when cloning a record through the user interface or
an API.
Note: The current number is updated only if the auto-number field value is set in a valid format.
File Upload field
The File Upload field type allows users to upload a file attachment that is stored in this field. The file will be
opened in a new browser window when clicked by the user.
You can specify a maximum size for files, from 128KB up to 2MB. In addition, the Advanced Field Properties
section allows you to Index this field as part of the text search engine, which automatically indexes files
uploaded into this field.
Check Make files publicly accessible if you want the content of uploaded file be accessible without checking
for a valid login session and user's access rights. If you upload a different file to a field that is publicly accessible,
the URL for that file does not change.
If the IsPDFAnnotationEnabled field is set to true in the System Console > System > Shared Properties >
General > Add/Remove Features, the Enable PDF Annotation checkbox assoicated with the File Upload
field is visible to enable the PDF editor function on the PDF files.
Note: When editing a File Upload or Image Upload file that holds a previously uploaded file, you have an
option to delete that file. This action cannot be undone, even if you cancel the entire record edit operation.
Image Upload field
The Image Upload field type allows end- users to upload an image file attachment that is stored in the field.
Pages that include the field will reference the images in an HTML <img> tag. You can specify Alternative text
for the image <alt> tag, which defines tooltip text to display when a user hovers their mouse over the image.
An Image Upload field, offers the following properties to control the image size:
• Maximum File Size
To limit storage space consumption, select a value to specify the maximum file size. For images over this
size, Rollbase will automatically resize them on upload.
• Maximum Image Size
Rollbase resizes images larger than the specified value automatically. For landscape images, the maximum
size (in pixels ) applies to the width. For portrait images, the maximum size applies to the height. When
Maximum Image Size is specified, Rollbase ignores the Maximum File Size property.
Image Upload and Shared Image fields are responsive by default. Responsive image fields change size to fit
the current screen size. You can specify that an image field is not responsive on a particular page; see
Responsive user interface on page 431 for details.
When an object definition contains multiple Image Upload fields, Rollbase groups the images into an image
carousel. The carousel is rendered where the first image field is located on the page. The width of the carousel
is based on the width of the cell in which the carousel is placed. By default, the height of the carousel is based
on the first image's proportions.
1312 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Field types
A carousel is responsive to the cell in which it is rendered on the page, keeping the proportions of the image.
It is responsive even if the images are not responsive. See Responsive user interface on page 431 for information
about configuring image responsiveness and maximum width.
Shared Image field
With the field type Shared Image, you can upload an image to be shared as a merge field in pages, templates
and formulas (including portal pages). Shared images are also stored and distributed with published applications.
You configure this field the same way as Image Upload fields, except that you must upload an actual image
file to be shared (128K max) in GIF, JPG, or PNG format.
Note: Use shared images throughout your apps for icons and logos to enhance the presentation and user
experience.
Shared Image and Image Upload fields are responsive by default. Responsive image fields change size to fit
the current screen size. You can specify that an image field is not responsive on a particular page; see
Responsive user interface on page 431 for details.
Formula Field
Formula field values are calculated from a formula and are automatically updated when any fields used in the
formula expression change value. You write formula field expressions in JavaScript. Rollbase executes them
to compute a dynamic output that can be displayed on the screen, and can be used by other components.
Formula fields can be displayed in views, see Views on page 142, but cannot be used for sorting, totaling, and
filtering of records in Views. Use an expression field instead to sort, total or filter. Formula fields execute
immediately when you create them and upon any update to the values to which they refer, while expression
fields only execute after an update operation.
In addition to fields that specify the label and appearance in views and reports, the New Field screen for a
formula field includes:
• The return type, which can be Decimal, Currency, Integer, String, Boolean, or Date.
• The currency format (only for fields with a Currency return type).
• The number of decimal places (only for fields with Decimal return type).
• An optional checkbox for hiding the display label of the field on UI Pages.
• The Formula Editor for defining the JavaScript expression. You can use merge fields from the current
object record and related records to return a dynamically computed value. This value can be numeric or
strings. Strings can consist of plain text, rich HTML, or JavaScript code that will be executed on the client's
browser. For more information about formulas, including examples, see Formulas on page 208.
Keep the following in mind when working with formula fields:
• To define loops, you can use the LOOP_BEGIN and LOOP_END tokens, as described in Iterating through
records on page 196. However, this technique should only be used for a small number of related records.
Looping through a large set of records using these tokens can degrade performance. It is better to use a
pre-defined function or the Rollbase Query API to obtain the required record. See the list of methods available
in the Query API on page 950.
• All merge tokens are replaced with the exact contents of the corresponding field's value before the formula
logic is executed. For example, a text field included by a token {!myTextField} with a value of Hello
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1313
Chapter 15: Reference
World will be used as is without the quotes around it. Always remember to use quotes around any value
where JavaScript requires them.
• To use dates:
• In a formula: create a JavaScript Date instance by providing the merge token with quotes around it as
the parameter:
var myDate = new Date("{!myDateField}");
• As the return type of a formula: return the full value of the JavaScript getTime() method. For example:
return myDate.getTime();
• When using images and shared images in formulas, wrap them in quotes to avoid errors. For example, the
following formula returns a different starred image (representing a star rating from 1 to 5) based on a picklist
value. In this example, the tokens {!star0} through {!star5} refer to hosted images and {!rating}
refers to a picklist:
if ({!rating}==106469)
return "{!star1}";
else if ({!rating}==106470)
return "{!star2}";
else if ({!rating}==106471)
return "{!star3}";
else if ({!rating}==106472)
return "{!star4}";
else if ({!rating}==106473)
return "{!star5}";
else
return "{!star0}";
Expression Field
Expression fields are similar to formula fields. Unlike formula fields, expression fields can be used for sorting,
totaling, and filtering of records in views. Expression field values are updated when a record is updated, while
formula field values update dynamically with any change.
Expression fields have the following limitations:
• Expression field values are updated when the containing record is updated — not when the record is viewed.
• The data type of an expression field cannot be changed.
• Unlike formula fields, expression fields are stored in the database, so they are subject to limitations on the
number of columns per object.
A list of most important features of Expression Fields is given below.
1. Related Object Token Support
The Template Helper box in the Expression field displays the related object tokens. These tokens can be
used to write any JavaScript formula to be evaluated as part of expression. Considering the scenario of a
Loan Management Application – Loan Type is displayed as a related object.
1314 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Field types
2. Field Dependency Selection
Field Dependency is a list of fields associated in an expression javascript formula. The expression field
re-calculates when any of the field present in the dependency list is updated. The user can move any of the
available fields to/from the assigned list.
On the click of Compute Dependency, Rollbase identifies a list of field tokens used in formulas and pull
respective field(s) from current object definition to Assigned Field section in dependency list.
On the selection of Any Field option under the Available Field List, Rollbase ensures the expression field
is updated on any update of the field present in the dependency list within a given object definition. From
the above screenshot, any update to the related object – Loan Type re-calculates the expression field while
disabling the remaining available list of fields.
Note:
• Compute dependency does not to pull fields from any other related object definition.
• In case the user wishes to select any individual fields, ensure the Any Field option is removed from the
Assigned Fields.
3. Reset Expression Field
This option re-calculates any given single expression field for all data records for the object definition. This
action can be performed on the Expression Field Definition view page.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1315
Chapter 15: Reference
On the click of Reset, a dialog prompts for the reset of the data under this expression field.
Reset of Expression Field can also be performed on the Customer Data Maintenance page.
Roll-Up Summary Field
With the Roll-Up Summary field type, user can conveniently build a Formula field that displays the sum, count,
minimum, or maximum value of all records related to the current record. When creating a Roll-Up Summary
field, you specify:
• A related object in the Related Object field.
• A numeric field of the object in the Field to Aggregate field.
• The sum of selected field for all related records, count or related records with not-null selected field, minimum
value of selected field for all related records, or maximum value of selected field for all related records in
the Compute What field.
Note: The Roll-Up Summary field type is exposed only if the selected object has a relationship with other
objects.
Template Field
A Template Field type is a non-editable Field that is automatically populated from a template expression you
define. When you define a template Field, you can use merge Fields and HTML markup from the current Object
record and any related records.
Tip: Template Fields (with a hidden display label) can be a good way to add client-side JavaScript to your
Application and Portal Pages.
1316 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Field types
Document Template Field
A Document Template Field type is a picklist that allows users to assign a document template to use for a
specific Object record. You can assign a default value to this Field and have it assigned to all existing records.
This Field renders a link to generate a document on the fly based on the selected document template using
the record's data. You can also use it in combination with a Create Template Document Trigger, see Trigger
overview on page 218.
When used as token in email templates, the Document Template Field will generate an email attachment with
the file generated from the document template for the current record.
Tip: Use Fields of this type when you want to allow users to select different types of document templates for
different Object records. For example, you may allow your sales users to select a different Quote Template
based on the type of order being created. Used with a Create Template Document trigger, you can automate
the creation of the appropriate type of document on an as-needed basis.
In View mode Document Template presents a link. When clicked, this link opens parsed document template
(populated with record's data) in pop-up window. You can specify size of that window in pixels (650 x 600 by
default). For HTML templates only you can choose to render them as PDF rather than HTML.
Email Template Field
The Email Template Field type is a picklist that allows users to assign an email template to use with a specific
Object record, similar to Document Template Field type. You can assign a default value to this Field and have
this default value assigned to all existing records. This Field renders a link to preview the email template using
the record's data. You can also use it in combination with a Send Email trigger and Send Email workflow action,
see Triggers and workflows on page 217.
Tip: Use Fields of this type when you want to allow users to select different types of email templates for different
Object records. For example, you may allow your sales users to select a different Quote Template based on
the type of order being created. Used with a Send Email trigger, you can automate an email based on the
appropriate email template on an as-needed basis.
Related Field
The Related Field type enables access to the value of a Field from a related Object. Related Fields allow you
to display and use Fields from related Objects. Before you can use a Field from another Object, you must
establish an N-to-1 or 1-to-1 Relationship from the current Object to the related Object.
When creating a related Field, select the appropriate related Object and then select the desired Field as shown
below:
Related Fields can be used to edit data of related Record if the following conditions are met:
• Option "Display this field in Edit mode on Edit pages" is checked
• Related Record is previously assigned.
Otherwise Related Fields are read-only on Pages.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1317
Chapter 15: Reference
Note: Modifying related record through Related Field will not invoke ant triggers
Integration Link Field
An Integration Link Field type is a custom link, typically used to pass Rollbase data to external systems, your
intranet, or other web-based applications by using merge Fields to insert the value of one or more Fields as
parameters in the URL. Integration link Fields display as links and they open in a new browser window when
clicked.
Integration link Fields work similar to URL Fields, but they allow the use of merge Fields to dynamically construct
a URL based on data in the current Object record, versus URL Fields which simply store a hard-coded URL.
Check "Use field's label as link and hide URL", otherwise actual URL will be shown in link.
Dependent Picklist Field
The Dependent Picklist Field type is a special type of single-select picklist that displays different available
values depending on the current selection in another (main) picklist. This main picklist must be selected before
creating a dependent picklist.
For each value of the main picklist, you can enter a comma-separated list of available values as shown below.
A typical example of a dependent picklist is a list of States or Provinces that depends on the selection of a
Country picklist. Once the selection in the Country picklist changes, Rollbase will automatically update the
available list of states.
Limitation: Each value in a dependent picklist may belong to only one value from the main picklist. If you need
to re-use values in dependent picklists because one or more values needs to be associated with more than
one value from the main picklist, you should instead create new Object definitions and use a lookup Field
dependency. See the Relationships section below for more information regarding configuring relationship
Lookup Fields to use Main and Link lookups to dynamically filter available selection choices.
Version Number Field
The Version number Field type specifically tracks record-level versions (versus auto-number Fields which are
more useful for Object level versioning). Version number Fields assign an integer value to a record when it is
created and you can configure them to increment that number whenever the record is updated or cloned.
1318 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Field types
Reference Field
With the Reference Field type, Users can reference any object record (typically parent) from current record
(typically child). When creating this field select group of object which can be referenced. At run time User can
select referenced Object type from drop-down list, then select actual record the same way as in Lookup field
(by type-ahead or from pop-up window).
Advanced field properties
In addition to basic field properties that vary based on the type of the field, Rollbase provides several advanced
field properties that determine various field characteristics. Not all of these properties are available for all field
types; for example, Image Upload and Formula fields cannot be indexed as part of the full text search engine.
• Index this field as part of the text search engine — This setting is available on text, numeric and date
fields, as well as on file uploads. If enabled, this field will be indexed and added to the global search engine
whenever a record is created and updated. Users will then be able to perform global and object-specific
searches on this field (field-specific searches in filters, etc., do not require enabling this property). If an
object definition does not have this option enabled for any field:
1. On the object definition page, Text Index Enabled is deselected.
2. The object is not listed in global search drop-down list. See Search on page 39 for more information
about global searches.
3. The Search box is not displayed on selector pages.
4. The Keywords box is not displayed on search pages
• Track all changes to this field in each record's Audit Trail for a complete historical log — Enabling
this property automatically adds a record-level audit trail entry whenever the field is updated, showing the
value of the field before and after the update, as well as the user that performed the update and the date
and time the update occurred. This option is only available if the parent object has Audit Trail Enabled
checked. See Auditing on page 169. for more information on auditing.
• Store uploaded files in an encrypted format. — This setting is only available for File Upload and Text
fields. After applying this setting, you cannot undo it.
Uploaded files are stored in encrypted format for added security and to meet compliance requirements. In
views, encrypted fields cannot be used for sorting.
• Always require a value in this field in order to save a record — This is a global setting specifying whether
this field is always required in form pages (such as New and Edit). If this property is enabled, it is not possible
to make this field non-required at the page level using the page editor.
• Do not allow duplicate values in this field — This setting is only available for text-based fields (including
auto-number). If set, it enforces uniqueness of this field's value across all records of that object type.
• This field allows inline editing from view pages by clicking on icon — When checked, users can edit
this field on record view pages by clicking the pencil icon.
• Allow filtering by this field in List Views — When checked (the default), this field will appear in the
drop-down list when filtering a view. When unchecked, this field will not appear in the drop-down list.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1319
Chapter 15: Reference
System Field Types
The following field types are Rollbase system fields.
Comments system field
The Comments field type is a text area which can be added to Edit and Status Change pages. Unlike other
text area fields, a Comments field stores its values in a Comments table. Every time a user enters a new value,
Rollbase adds a new comment record to the table. You can add a Comments table to a View page:
Users can click the comment icon above the Comments table to add a new comment.
You can use Comments fields in templates and formulas. When doing so, the Comments field's value is the
text of the most recently created comment.
iCal System Field
The iCal Field type is a read-only Field, automatically generated when you select an Event or Task attribute.
It will render a link that you can use to synchronize your event or task with Microsoft Outlook or other programs
using export in iCal format.
When used as token in email templates, the iCal Field will generate an email attachment with a file in iCal
format.
1320 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Field types
vcard System Field
The vCard Field type is a read-only Field, automatically generated when you select the Contact attribute. It will
render a link that you can use to synchronize your contact with Microsoft Outlook or other programs using
export in vCard format.
When used as token in email templates, the vCard Field will generate email attachment with a file in vCard
format.
Organization Data System Fields
Tree Fields of this type (Location, Department and Function) are automatically created when you select the
"Organization" attribute for an Object. These Fields keep track on location of your record relative to LDF trees.
See Location/department/function permissions on page 669.
If you check "Use user's Function value as default for new records" for this Field type, LDF attribute from user
will be copied by default to newly created record.
Time Zone System Field
This field is used to select time zone for Rollbase users. Selected time zone will be used to calculate offset for
date/time values before displaying them. Choose from the list of existing time zones. If no time zone is selected
- time zone setting from Account info (Customer settings) will be used.
You can check "Use browser's settings to suggest time zone for new records" on field edit page. Please note
that suggested time zone will have the same offset value, but it not necessarily will be actual user's time zone.
User Role Field
This field is only available for system User objects and used to select a user's role. See Role-based access
control on page 648 for more information. On the field edit page, you can select the role to be used as the default
for new users (No Access if no selection is made).
For security reasons, a user's role can be only assigned by an administrator. For all non-administrative users,
the User Role field is read-only.
LDF Filter Field
This Field type is used to visualize LDF permissions for a particular record and user.
Parent Object Field
This Field is a part of Communication Log system object and points to a record to which particular Log refers.
This is a required field. The system automatically populates it when new Communication Log record is created.
Tag Field
This field displays search tags assigned for a particular record by different users.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1321
Chapter 15: Reference
Portal Field Types
The following Field types are typically only used in external-facing Portals. See Rollbase portals on page 524.
Captcha Image Field
The Captcha Image Field type requires that the user type letters and digits displayed in a distorted image to
ensure that the user is in fact a human, rather than a computer. Form submission will not work if the entry is
not correct. For example, the figure below shows how a Captcha Image might appear in a Portal Page. See
Rollbase portals on page 524 for more information.
Hidden Input Field
The Hidden Input Field type allows you to capture any URL parameter, such as a campaign id or source, from
the original URL the visitor used to reach your Portal. You also have an option to capture HTTP cookie instead
of URL parameter.
IP Address Field
The IP Address Field type provides a convenient way to capture, store and resolve the IP address of Portal
users. This Field is particularly useful in Portals that require authentication and allow self-registration, see
Rollbase portals on page 524. This Field will also resolve to display the country code of the IP address, allowing
you to receive real information about the source of each of your requests.
Rollbase SOAP Methods
Many of the topics in this section include code samples written in Java using the Axis package.
Rollbase SOAP API WSDL
The Rollbase SOAP API WSDL is located at: https://www.rollbase.com/webapi/wsdl/api.wsdl. This link is
available in Setup Home, under Applications Setup > API. Rollbase uses Literal WSDL encoding. If your
SOAP infrastructure does not support Literal WSDL encoding, consider using the REST API.
Working with Field Data
When working with records using the Rollbase SOAP API, you use a special container called DataField.
This serves as a container for data stored in a single record field and includes the following attributes:
• Integration name (mandatory): Integration name of the field the data belongs to.
1322 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Rollbase SOAP Methods
• Data value: the actual data that belongs to the field in this record, represented as string. The string format
depends on the type of the given field:
• For check boxes: true or false, yes or no
• For numeric fields: a numeric value as decimal string
• For single picklists: the integration code of the selected item or item name
• For multi-select picklists: the integration codes of the selected items or item names separated by the "|"
symbol
• For lookup fields: the numeric IDs or names (must be unique) of related records separated by the "|"
symbol
• For date fields: a date string in the format corresponding to the current user's date format preference.
Example: 05/01/2009
• For date and time fields: a date-time string in the format corresponding to the current user's date format
preference. The time zone for this string is the same as time zone selected in the current user's
preferences. For example: 05/01/2009 1:00 PM is interpreted as 05/01/2009 1:00 PM PST, if the current
user has the PST time zone setting.
Permissions
Most SOAP methods require the logged-in user to have the appropriate permission for the type of object used
in the method call. For example, calling the the create() method to create a Customer record requires the
logged-in user to have Create permission on the Customer object. The documentation for each method includes
the required permissions.
It is a good practice for SOAP clients to use credentials of users with the role Server API. Users with that role
cannot log into Rollbase as regular users.
DataObj Container Class
Purpose
Container class for a complete record. You can use this class to pass a complete record with all of its fields to
a method. Methods that return a complete record return an instance of this class. Attribute names are
case-sensitive.
For Rollbase objects, you must include the id and objDefName. For external objects, you must include the
UID and objDefName.
Class Attributes
id
A string containing the record ID.
UID
A string containing the object ID for external objects, including objects mapped to OpenEdge Services.
objDefName
A string containing the object definition integration name.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1323
Chapter 15: Reference
DataFieldArr
An array of DataField instances containing the values for the record's fields.
Example
See getRecord() on page 1350 for an example.
DataField Container Class
Purpose
Container class for a record's field. You can use this class to pass a field to a method. Methods that return a
field return an instance of this class. Field names are case-sensitive.
Class Attributes
name
The name of the field.
value
The value of the field.
Example
See create() on page 1328, getDataField() on page 1342, and setDataField() on page 1358 for examples.
SearchFilter Class
Purpose
Defines a single search filter for the detailedSearch() on page 1338 method's filterArr parameter. There can
be up to five SearchFilters per search, and they are passed to the method in an array.
Parameters
fieldName
String name of data field used for filtering
opCode
Code of operation. The following codes are available. Not all codes are compatible with all fields;
the same rules apply as in the Detailed search on page 374 component.
• EQ equals
• NEQ not equal
• ST starts with
• CT contains
1324 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Rollbase SOAP Methods
• NCT does not contain
• LT less than
• GT greater than
• LE less or equal
• GE greater or equal
• IN in array
• NIN not in array
• CH checked
• NCH unchecked
• INC including
• NINC not including
• NUL is null
• NNUL not null
• IS is
• TREE in sub-tree
• NTREE not in sub-tree
• FLAG flagged
• UFLAG unflagged
• VIEW viewed
• UVIEW unviewed
opValue
Filter's value as a string. Use comma-separated enumerations for arrays.
Example
SearchFilter[] filters = new SearchFilter[1];
SearchFilter filter = new SearchFilter();
filter.setFieldName("firstName");
filter.setOpCode("EQ");
filter.setOpValue("Smith");
filters[0] = filter;
SearchFilterArr filterArr = new SearchFilterArr(filters);
LongArr arr = binding.detailedSearch(sessionId, null, "lead", filterArr, "AND", null);
long[] ids = arr.getArr();
bulkCreate()
Purpose
Creates new records using an existing import map and a supplied CSV string.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1325
Chapter 15: Reference
Syntax
bulkCreate(string sessionId, string mapId, boolean sync, string csvString);
Parameters
sessionId
A string containing the session ID obtained at log in.
mapId
The original ID of an existing import map.
sync
A boolean value: if true, do synchronous import and return IDs of created records; if false, do
asynchronous import.
csvString
A CSV string containing import data.
Output
Comma-separated IDs of newly created records for synchronous import
Permissions Required
Create permission for the requested object types.
bulkCreateUpdate()
Purpose
Updates existing records or creates new ones using an existing import map and a supplied CSV string.
Syntax
bulkCreateUpdate(string sessionId, string mapId, [string
uniqueFieldId|uniqueCombinationId], boolean sync, string csvString);
Parameters
sessionId
A string containing the session ID obtained at log in.
mapId
The original ID of an existing import map.
uniqueFieldId
ID of a unique field used to identify the records to be updated
1326 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Rollbase SOAP Methods
uniqueCombinationId
ID of a Unique Fields Combination trigger
sync
A boolean value: if true, do synchronous import and return IDs of created records; if false, do
asynchronous import.
csvString
A CSV string containing import data.
Output
Comma-separated IDs of updated records for synchronous update
Permissions Required
Edit permission for the object type of each requested record. Create permission for the object type of each
new record.
bulkUpdate()
Purpose
Updates existing records using an existing import map and a supplied CSV string.
Syntax
bulkUpdate(string sessionId, string mapId, [string
uniqueFieldId|uniqueCombinationId], boolean sync, string csvString);
Parameters
sessionId
A string containing the session ID obtained at log in.
mapId
The original ID of an existing import map.
uniqueFieldId
ID of unique field used to identify records to be updated
uniqueCombinationId
ID of the Unique Fields Combination trigger
sync
A boolean value: if true, do synchronous import and return IDs of created records; if false, do
asynchronous import.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1327
Chapter 15: Reference
csvString
A CSV string containing import data.
Output
Comma-separated IDs of updated records for synchronous update
Permissions Required
Edit permission for the requested object types.
clearDataObjectCache()
Purpose
Clears the cache of object data records from production servers. Progress recommends that you call this
method after heavy use of the SOAP API to perform updates.
Syntax
clearDataObjectCache(sessionId);
Parameters
sessionId
A string containing the session ID obtained at log in.
Output
None
Permissions Required
All metadata methods require administrative privileges, regardless of the view, edit, create and delete permissions
set on the application or object. Establish the session by logging in with credentials for an administrative user.
Example
Output example:
<resp status="ok">
<Msg>Cleared cache of object records</Msg>
</resp>
create()
Purpose
Creates a new record.
This method only works with native Rollbase objects. To create an external object record, see createRecord()
on page 1333
1328 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Rollbase SOAP Methods
Syntax
create(string sessionId, string objDefName, DataFieldArr arr, boolean useIds);
Parameters
sessionId
A string containing the session ID obtained at log in.
objDefName
String containing Integration name for object definition
arr
A DataFieldArr array of values for fields of a newly created record. Record ID and auto-numbers
are assigned automatically.
useIds
A boolean value: if true, use numeric IDs for lookup and picklist values; otherwise, use integration
codes and record names.
Output
ID of newly created record as a long
Permissions Required
Create permission for the requested object type.
Example
// Populate data Fields to be set for new record
DataField[] Fields = new DataField[5];
DataField Field = new DataField();
Field.setName("firstName");
Field.setValue("John");
Fields[0]=Field;
Field.setName("lastName");
Field.setValue("Smith");
Fields[1]=Field;
// Call create API
binding.create(sessionId, "lead", new DataFieldArr(Fields), true);
createArr()
Purpose
For native Rollbase objects, this method creates an array of new object records. This API increments the hits
counter for each array element. This method and createArrNoAudit() each take an array of transport
Objects of type DataObj wrapped in a DataObjArr instance. This transport Object carries:
• Object name
• Record ID (for update only)
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1329
Chapter 15: Reference
• Fields to be set
This is a convenient form for transporting data. Note that, this API is optimized for faster performance in cases
when related records must be resolved by name.
Note: For external objects (such as those mapped to external tables, to OpenEdge Service objects, or through
a D2C connection), you can use the method, createArr2() on page 1331.
Syntax
createArr(string sessionId, DataObjArr arr, boolean useIds);
Parameters
sessionId
A string containing the session ID obtained at log in.
arr
A DataObjArr array of DataObjs with data for new records. Record IDs and auto-numbers are
assigned automatically.
useIds
A boolean value: if true, use numeric IDs for lookup and picklist values; otherwise, use integration
codes and record names.
Output
Ids of newly created records as a LongArr
Required Permissions
Create permission for the requested object type.
Example
// Array of transport objects to be sent to createArr
DataObj[] arr = new DataObj[10];
// Populate data Fields to be set for record 0
DataField[] Fields = new DataField[5];
DataField Field = new DataField();
Field.setName("amount");
Field.setValue("1000");
Fields[0]=Field;
// Create record 0
DataObj obj = new DataObj();
obj.setObjDefName("lead");
obj.setFields(Fields);
arr[0] = obj;
// Repeat for record 1
// Call createArr API
binding.createArr(sessionId, new DataObjArr(arr), false);
1330 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Rollbase SOAP Methods
createArr2()
Purpose
For external objects (such as those mapped to external tables, to OpenEdge Service objects, or through a D2C
connection), creates an array of new object records. This API increments the hits counter for each array element.
This transport Object carries:
• Object name
• Record ID (for update only)
• Fields to be set
This is a convenient form for transporting data.
Note: createArr API is optimized for faster performance in cases when related records must be resolved by
name.
Note: For native Rollbase objects, you can use the method, createArr() on page 1329.
Syntax
createArr2(string sessionId, DataObjArr arr, boolean useIds);
Parameters
sessionId
A string containing the session ID obtained at log in.
arr
A DataObjArr array of DataObjs with data for new records. Record IDs and auto-numbers are
assigned automatically.
useIds
A boolean value: if true, use numeric IDs for lookup and picklist values; otherwise, use integration
codes and record names.
Output
Ids of newly created records as a StringArr
Required Permissions
Create permission for the requested object type.
Example
// Array of transport objects to be sent to createArr
DataObj[] arr = new DataObj[10];
// Populate data Fields to be set for record 0
DataField[] Fields = new DataField[5];
DataField Field = new DataField();
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1331
Chapter 15: Reference
Field.setName("amount");
Field.setValue("1000");
Fields[0]=Field;
// Create record 0
DataObj obj = new DataObj();
obj.setObjDefName("lead");
obj.setFields(Fields);
arr[0] = obj;
// Repeat for record 1
// Call createArr2 API
binding.createArr2(sessionId, new DataObjArr(arr), false);
createArrNoAudit()
Purpose
Creates an array of new object records. This API increments the hits counter for each array element. This is
the same as createArr(), except that it blocks Audit records.
Syntax
createArrNoAudit(string sessionId, DataObjArr arr, boolean useIds);
Parameters
sessionId
A string containing the session ID obtained at log in.
arr
A DataObjArr array of DataObjs with data for new records. Record IDs and auto-numbers are
assigned automatically.
useIds
A boolean value: if true, use numeric IDs for lookup and picklist values; otherwise, use integration
codes and record names.
Output
Ids of newly created records as a LongArr
Required Permissions
Create permission for the requested object type.
1332 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Rollbase SOAP Methods
createCustomer()
Purpose
Starts the process of creating a new customer tenant. A welcome email containing a temporary password is
sent to the first administrative user when the process is complete. If the password field is included in the list of
fields, as in the example below, its value is used as the password for the first administrative user. In this case,
the system does not send the welcome email to first administrative user and the password will not expire after
the first log in.
Syntax
createCustomer(string sessionId, DataFieldArr arr, boolean useIds);
Parameters
sessionId
A string containing the session ID obtained at log in.
arr
A DataFieldArr array of values for fields of a newly created record. Record ID and auto-numbers
are assigned automatically.
useIds
A boolean value: if true, use numeric IDs for lookup and picklist values; otherwise, use integration
codes and record names.
Output
ID of newly created Customer
Permissions Required
Create permission for the Customer object type
Example
DataField[] arr = new DataField[7];
arr[0] = getField("companyName", "API Test");
arr[1] = getField("email", "[email protected]");
arr[2] = getField("lastName", "Admin");
arr[3] = getField("loginName", "[email protected]");
arr[4] = getField("timeZone", "Pacific/Guam");
arr[5] = getField("mailSender", "[email protected]");
arr[6] = getField("password", "my_password");
binding.createCustomer(sessionId, new DataFieldArr(arr), true);
createRecord()
Purpose
Similar to create() on page 1328, creates a new record. Returns the ID of the newly created record.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1333
Chapter 15: Reference
This method works with external objects (including those mapped to OpenEdge services) and native Rollbase
objects.
Syntax
createRecord(string sessionId, string objDefName, DataFieldArr arr, string useIds);
Parameters
sessionId
A string containing the session ID obtained at log in.
objDefName
A string containing the object definition integration name.
arr
A DataFieldArr array of values for fields of a newly created record. Record ID and auto-numbers
are assigned automatically.
useIds
A boolean value: if true, use numeric IDs for lookup and picklist values; otherwise, use integration
codes and record names.
Output
The ID of the newly created record as a string.
Permissions Required
Create permission for the requested object type.
delete()
Purpose
Moves the specified record to the Recycle Bin. For users and Customers this API deletes records permanently.
This method only works with native Rollbase objects. To delete an external object record, see deleteRecord()
on page 1336.
Syntax
delete(string sessionId, long id);
Parameters
sessionId
A string containing the session ID obtained at log in.
1334 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Rollbase SOAP Methods
id
A long value containing the record ID.
Output
None
Permissions Required
Delete permission for the requested object type.
Example
long id = 123456;
binding.delete(sessionId, id);
deleteArr()
Purpose
For native Rollbase objects, this method moves the specified array of records to the Recycle Bin. This method
increments the hits counter for each array element.
Note: For external objects (such as those mapped to external tables, to OpenEdge Service objects, or through
a D2C connection), you can use the method, deleteRecords() on page 1337.
Syntax
deleteArr(string sessionId, LongArr ids);
Parameters
sessionId
A string containing the session ID obtained at log in.
ids
LongArr array of record ids to be deleted.
Output
None
Permissions Required
Delete permission for the requested object type.
Example
long[] ids = new long[] { 123456, 123457 };
binding.deleteArr(sessionId, new LongArr(ids));
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1335
Chapter 15: Reference
deleteArrNoAudit()
Purpose
For native Rollbase objects, this method moves the specified array of records to the Recycle Bin. Similar to
deleteArr(), except deleteArrNoAudit() blocks Audit records. This method will increment the hits counter
for each array element.
Note: For external objects (such as those mapped to external tables, to OpenEdge Service objects, or through
a D2C connection), you can use the method, deleteRecords() on page 1337.
Syntax
deleteArrNoAudit(string sessionId, LongArr ids);
Parameters
sessionId
A string containing the session ID obtained at log in.
ids
LongArr array of record ids to be deleted.
Output
None
Permissions Required
Delete permission for the requested object type.
deleteRecord()
Purpose
Moves an object record to the recycle bin.
This method works with external object records (including those mapped to OpenEdge services) and native
Rollbase object records.
Syntax
deleteRecord(string sessionId, string objDefName, string uid);
Parameters
sessionId
A string containing the session ID obtained at log in.
1336 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Rollbase SOAP Methods
objDefName
A string containing the object definition integration name.
uid
A string containing the record ID.
Output
None.
Permissions Required
Delete permission for the requested object type.
deleteRecords()
Purpose
For external objects (such as those mapped to external tables, to OpenEdge Service objects, or through a D2C
connection), this method moves the specified array of records to the Recycle Bin. This method will increment
the hits counter for each array element.
Note: For native Rollbase objects, you can use the method, deleteArr() on page 1335 and deleteArrNoAudit()
on page 1336.
Syntax
deleteRecords(string sessionId, String objDefName, StringArr ids, Boolean
blockAudit);
Parameters
sessionId
A string containing the session ID obtained at log in.
objDefName
A string containing the object definition integration name.
ids
StringArr array of record ids to be deleted.
blockAudit
If set to true, no audit records are created.
Output
None
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1337
Chapter 15: Reference
Permissions Required
Delete permission for the requested object type.
Example
Introduce example here.
String[] arr = new String[] { "100890", "100891" };
binding.deleteRecords(sessionId, "client", new StringArr(arr));
detailedSearch()
Purpose
Performs a detailed search throughout the customer's Rollbase database. This is equivalent to the search
capabilities provided by the Detailed search on page 374 component.
Syntax
detailedSearch(string sessionId, string query, string objDefName, SearchFilterArr
filterArr, string joinType, string expression)
Parameters
sessionId
A string containing the session ID obtained at log in.
query
String query for full-text search (see above)
objDefName
String integration name for selected object definition. This parameter is optional and allows you to
narrow the search to a specified object.
filterArr
SearchFilterArr instance which wraps an array of SearchFilter instances. See SearchFilter Class
on page 1324 for more information.
joinType
Type of join between filters. Valid values are: AND (default), OR, or null (if expression is present)
expression
String SQL Expression that includes tokens for filters. Example: ((1 OR 2) AND 3)
Output
IDs of all records found in the search, returned as LongArr
1338 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Rollbase SOAP Methods
Example
SearchFilter[] filters = new SearchFilter[1];
SearchFilter filter = new SearchFilter();
filter.setFieldName("firstName");
filter.setOpCode("EQ");
filter.setOpValue("Smith");
filters[0] = filter;
SearchFilterArr filterArr = new SearchFilterArr(filters);
LongArr arr = binding.detailedSearch(sessionId, null, "lead", filterArr, "AND", null);
long[] ids = arr.getArr();
getBinaryData()
Purpose
Retrieves the file attachment associated with a particular file field from a specific record.
Syntax
getBinaryData(string sessionId, long id, string fieldName);
Parameters
sessionId
A string containing the session ID obtained at log in.
id
A long value containing the record ID.
fieldName
A string containing the field integration name.
Output
Binary data (file attachment) from specified file Field wrapped in a ByteArr
Permissions Required
View permission for the requested object type.
Example
long id = 123456;
ByteArr arr = binding.getBinaryData(sessionId, id, "picture");
if (arr != null {
byte[] data = arr.getArr();
}
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1339
Chapter 15: Reference
getCodebyId()
Purpose
Retrieves the integration code of a picklist item or status by ID.
Note: This API only works when the ID is numeric. Therefore, Picklist(char) or Radio Button(char) are not
supported.
Syntax
getCodeById(string sessionId, string objDefName, string fieldName, long id);
Parameters
sessionId
A string containing the session ID obtained at log in.
objDefName
String containing integration name of object definition
fieldName
String containing integration name of Field (picklist or status)
id
Long numeric ID of picklist item or status
Output
Integration code of item with matching ID or null
Example
String code = binding.getCodeById(sessionId, "lead", "type", 98765);
getCount()
Purpose
Retrieves the total number of records in a view (see Working with views on page 437 for more information about
views).
Syntax
getCount(string sessionId, string viewId, string filterName, string filterValue);
1340 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Rollbase SOAP Methods
Parameters
sessionId
A string containing the session ID obtained at log in.
viewId
The original ID of the view.
filterName
The name of the field to filter output using the equals option (will replace the filter set in the view,
if any).
filterValue
The value of the field to filter output using the equals option.
Output
Number of Records
Permissions Required
View permission for the requested object type.
Example
int count = binding.getCount("7ae747a0e36648ef8bd016eec1502779@46216462", "123",
"lastName", "Grey");
getIdByCode()
Purpose
Retrieves the ID of the pick item or status by integration code.
Note: This API only works when the ID is numeric. Therefore, Picklist(char) or Radio Button(char) are not
supported.
Syntax
getIdByCode(string sessionId, string objDefName, string fieldName, string code);
Parameters
sessionId
A string containing the session ID obtained at log in.
objDefName
String containing integration name of object definition
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1341
Chapter 15: Reference
fieldName
String containing integration name of Field (picklist or status)
code
String containing integration name of picklist item or status
Output
ID of item with matching integration code or -1
Example
long id = binding.getIdByCode(sessionId, "lead", "type", "HOT");
getDataField()
Purpose
For native Rollbase objects, this method retrieves the value of a single field from a specific record.
Note: For external objects (such as those mapped to external tables, to OpenEdge Service objects, or through
a D2C connection), you can use the method, getDataField2() on page 1343.
Syntax
getDataField(string sessionId, long id, string fieldName, boolean useIds);
Parameters
sessionId
A string containing the session ID obtained at log in.
id
A long value containing the record ID.
fieldName
A string containing the field integration name.
useIds
A boolean value: if true, use numeric IDs for lookup and picklist values; otherwise, use integration
codes and record names.
Output
Field's value wrapped in a DataField container.
Permissions Required
View permission for the requested object type.
1342 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Rollbase SOAP Methods
Example
long id = 123456;
DataField field = binding.getDataField(sessionId, id, "lastName", false);
if (field != null) {
String lastName = field.getValue();
}
getDataField2()
Purpose
For external objects (such as those mapped to external tables, to OpenEdge Service objects, or through a D2C
connection), this method retrieves the value of a single field from a specific record.
Note: For native Rollbase objects, you can use the method, getDataField() on page 1342.
Syntax
getDataField2(string sessionId, String objDefName, String uid, String fieldName,
Boolean useIds);
Parameters
sessionId
A string containing the session ID obtained at log in.
objDefName
A string containing the object definition integration name.
uid
A string containing the record ID.
fieldName
A string containing the field integration name.
useIds
A boolean value: if true, use numeric IDs for lookup and picklist values; otherwise, use integration
codes and record names.
Output
Field's value wrapped in a DataField container.
Permissions Required
View permission for the requested object type.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1343
Chapter 15: Reference
Example
DataField field = binding.getDataField2(sessionId, "client", "123456", "lastName", false);
if (field != null) {
String lastName = field.getValue();
}
getDataObj()
Purpose
Warning: This method is deprecated. Please change any existing code to use getRecord() on page
1350, which takes an object ID as a parameter.
Retrieves all field data, including formulas, for a given record.
Syntax
getDataObj(string sessionId, long id, boolean useIds);
Parameters
sessionId
A string containing the session ID obtained at log in.
id
A long value containing the record ID.
useIds
A boolean value: if true, use numeric IDs for lookup and picklist values; otherwise, use integration
codes and record names.
Output
All of the field data for the specified object record. Each field value is wrapped in a DataField container.
Permissions Required
VIEW permission for requested record
Example
long id = 123456;
DataObj obj = binding.getDataObj(sessionId, id, true);
if (obj != null) {
DataField[] fields = obj.getFields();
}
1344 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Rollbase SOAP Methods
getExchangeRate()
Purpose
Returns the exchange rate between two currencies on the given date.
Syntax
getExchangeRate(string sessionId, string srcCode, string destCode, Calendar date);
Parameters
sessionId
A string containing the session ID obtained at log in.
srcCode
The currency code to convert from.
destCode
The currency code to convert to.
date
The Calandar object containing the date.
Output
Exchange rate as decimal
Example
Calendar today = Calendar.getInstance();
today.setTime(new Date());
double rate = binding.getExchangeRate(sessionId, "EUR", "USD", today);
getPage()
Purpose
Retrieves a specified range of data records in a view. The selected view defines sorting and filtering of the
output. The amount of processing and time required to get complete results can vary widely, depending on
whether it fetches related records and the number of rows you specify per page.
Syntax
getPage(string sessionId, string viewId, string filterName, string filterValue,
int startRow, int rowsPerPage, boolean useIds);
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1345
Chapter 15: Reference
Parameters
sessionId
A string containing the session ID obtained at log in.
viewId
The original ID of the view.
filterName
The name of the field to filter output using the equals option (will replace the filter set in the view,
if any).
filterValue
The value of the field to filter output using the equals option.
startRow
An integer representing the number of the data record to start from.
rowsPerPage
An integer representing the number of data records in output.
useIds
A boolean value: if true, use numeric IDs for lookup and picklist values; otherwise, use integration
codes and record names.
Output
Selected records as DataObjArr
Permissions Required
View permission for the requested object type.
Example
DataObj[] arr = binding.getPage("7ae747a0e36648ef8bd016eec1502779@46216462", "25513", "
lastName", "Grey ", 0, 20, false).getObjects();
for (DataObj obj: arr) {
System.out.println("\nID="+obj.getId()+
" objName="+obj.getObjDefName());
DataField[] fields = obj.getFields();
for (DataField field: fields) {
System.out.println("Name="+field.getName()+
" Value="+field.getValue());
}
}
1346 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Rollbase SOAP Methods
getRelatedIDs()
Purpose
Retrieves an array of related record IDs. Unlike getRelationships(), this API works with external objects,
including those based on OpenEdge services.
Syntax
getRelatedIDs(sessionId, objDefName, id, relName);
Parameters
sessionId
A string containing the session ID obtained at log in.
objDefName
A string containing the object definition integration name.
id
A string containing the record ID.
relName
A string containing the relationship integration name.
Output
A stringArr containing a list of related record IDs.
Permissions Required
View permission for the requested object types.
Example
The following example returns the IDs of the records related to the oeTest object through the R291855
relationship.
LongArr arr = binding.getRelatedIDs(sessionId, "oeTest", "789456", "R291855");
if (arr != null) {
String[] ids = arr.getArr();
}
getRelationships()
Purpose
Retrieves an array of related record IDs.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1347
Chapter 15: Reference
Note: This method does not work for external objects. Use getRelatedIDs() on page 1347 for external objects,
including those mapped to OpenEdge services.
Syntax
getRelationships(string sessionId, long id, string relName);
Parameters
sessionId
A string containing the session ID obtained at log in.
id
A long value containing the record ID.
relName
Relationship's integration name
Output
IDs of related records wrapped in a LongArr
Permissions Required
View permission for the requested object types.
Example
long id = 123456;
LongArr arr = binding.getRelationships(sessionId, id, "R76543");
if (arr != null {
long[] ids = arr.getArr();
}
getRuntimeStatus()
Purpose
Retrieves the runtime status of the Customer on the Web API server.
Syntax
getRuntimeStatus(string sessionId, long id);
Parameters
sessionId
A string containing the session ID obtained at log in.
1348 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Rollbase SOAP Methods
id
A long value containing the record ID.
Output
Runtime status:
• RUNTIME_ERROR = -1;
• RUNTIME_UNLOADED = 1;
• RUNTIME_LOADED = 2;
• RUNTIME_LOADING = 3;
• RUNTIME_CREATING = 4;
• RUNTIME_BUSY = 5;
Permissions Required
View permission for the Customer type.
Example
int status = binding.getRuntimeStatus(sessionId, 123456);
getUpdated()
Purpose
Retrieves an array of record IDs of a specified object type that were either created or updated within the given
date/time interval. This method is not available for external objects, including those mapped to OpenEdge
service objects.
Syntax
getUpdated(string sessionId, Calendar from, Calandar till, string objDefName);
Parameters
sessionId
A string containing the session ID obtained at log in.
from
Beginning of date/time interval (not null)
till
End of date/time interval or null
objDefName
String integration name for object definition to search
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1349
Chapter 15: Reference
Output
IDs of all records found in the search, returned as LongArr
Example
Calendar from = Calendar.getInstance();
from.setTime(...);
Calendar till = null;
LongArr arr = binding.getUpdated(sessionId, from, till, "lead");
long[] ids = arr.getArr();
getRecord()
Purpose
Retrieves all field data (including formulas) for a given record in XML format. This method works with external
objects, including those mapped to OpenEdge services.
Syntax
getRecord(string sessionId, string objDefName, string uid, boolean useIds);
Parameters
sessionId
A string containing the session ID obtained at log in.
objDefName
A string containing the object definition integration name.
uid
A string containing the object ID.
useIds
A boolean value: if true, use numeric IDs for lookup and picklist values; otherwise, use integration
codes and record names.
Output
All of the field data for the specified object record. Each field value is wrapped in a DataField container. See
DataField Container Class on page 1324 for more information.
Permissions Required
View permission for the requested object type.
Example
DataObj obj = binding.getRecord(sessionId, "client", "123456", true);
1350 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Rollbase SOAP Methods
if (obj != null) {
DataField[] fields = obj.getFields();
}
login()
Purpose
Performs a user log in and initiates a SOAP API session. Either this method or login2() (see below) must
be called prior to any other API call. The customer tenant to login is determined by the login name. The Web
API login creates a server-side session which might expire according to the security level set for the customer
tenant (see Security and Access Control for more information).
The API client should re-login if the session expires. Progress recommends that an API client logs out after
performing a group of operations instead of keeping the API session open for a long time. When an API client
logs in, all sessions with the same user credentials are terminated.
Subsequent API calls that use a session ID are considered to be made on behalf of the logged in user. That
user's permissions are checked for each subsequent call. For example, to update a record a logged in user
must have sufficient permissions or the API call will fail.
Syntax
login(string loginName, string password);
Parameters
loginName
String containing login name for an active Rollbase user account
password
String containing user password
Output
Session ID that must be used in all subsequent API calls during this session
login2()
Purpose
Performs regular user or super-admin login to the specified customer tenant and initiates a SOAP API session.
Unlike the login() method, the customer to login to is specified explicitly by ID. Master Server users with
super-admin login permissions can use login2() to call Web Service APIs on the specified customer tenant.
Syntax
login2(string loginName, string password, string custID);
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1351
Chapter 15: Reference
Parameters
loginName
String containing login name for an active Rollbase user account
password
String containing user password
custID
ID of customer tenant to log into
Output
Session ID that must be used in all subsequent API calls during this session
logout()
Purpose
Terminates the specified API session. This method should be called to explicitly end each SOAP session.
Syntax
logout(string sessionID);
Parameters
sessionId
A string containing the session ID obtained at log in.
Output
None
Example
URL url = new URL("https://www.rollbase.com/webapi/services/rpcrouter");
RpcrouterSoapBindingStub binding = (RpcrouterSoapBindingStub)
new IWebServicesServiceLocator().getrpcrouter(url);
binding.setTimeout(60000);
String sessionId = binding.login("username", "password");
System.out.println("loginsuccessful: sessionId="+sessionId);
// Perform some API calls
binding.logout(sessionId);
1352 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Rollbase SOAP Methods
resetPassword()
Purpose
Resets the password of the specified user.
Syntax
resetPassword(string sessionId, string loginName);
Parameters
sessionId
A string containing the session ID obtained at log in.
loginName
Login name for an active Rollbase user account in the same tenant
Output
None
Permissions Required
Requires administrative privileges. Establish the session by logging in with credentials for an administrative
user.
selectNumber()
Purpose
Runs an SQL SELECT query on the server and returns a single decimal value as the result. This is a simplified
version of selectQuery() and is suitable for calculations such as finding a sum of values.
The SELECT query used in this method consists of the following parts:
• The SELECT statement expects columns or expressions to be selected (mandatory). Use the field integration
names as SQL column names. You can use expressions such as COUNT(1). You cannot use * to retrieve
all columns.
• The FROM clause must consist of exactly one object name (mandatory).
• The WHERE clause can include a valid SQL expression to narrow the selection (optional). Use field integration
names as SQL column names.
• The ORDER BY clause can include a valid SQL expression to order the selection (optional). Use field
integration names as SQL column names.
You can use special tokens in your queries such as:
• TODAY for current time
• WEEK for 12PM of last Sunday
• MONTH for 12PM of 1st day of current month
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1353
Chapter 15: Reference
• QUARTER for 12PM of 1st day of current quarter
• YEAR for 12PM of 1st day of current year
• CURR_USER for id of currently logged in user
Object and Field names are case-sensitive, while other components of the SQL query are not.
Use #code suffix to fetch integration codes for picklist fields rather than IDs. See Adding Logic to an Application
for more information.
Syntax
selectNumber(string sessionId, string query);
Parameters
sessionId
A string containing the session ID obtained at log in.
query
An SQL SELECT query. See the examples described for selectQuery().
Output
Single result of the SELECT query as a decimal number
Permissions Required
View permission for the requested object type.
Example
Double total = binding.selectNumber(sessionId,
"SELECT SUM(amount) FROM customer WHERE name LIKE 'M%'");
selectQuery()
Purpose
Runs a SQL SELECT query on the server and returns the results as a 2D-array. Either the current user or the
API user must have View access for all records of the given type.
The selectQuery() method, as well as selectValue() and selectNumber(), use the same permissions
model as the server-side query API (see for more details).
Examples of valid queries on the User object (you can find more examples in Adding Logic to an Application):
SELECT id, name, updatedAt, updatedBy FROM USER WHERE name LIKE 'M%' ORDER BY name
SELECT count(1) FROM USER WHERE name LIKE 'M%'
SELECT count(1) FROM USER WHERE updatedBy>=QUARTER
The SELECT query used in this method consists of the following parts:
1354 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Rollbase SOAP Methods
• The SELECT statement expects columns or expressions to be selected (mandatory). Use the field integration
names as SQL column names. You can use expressions such as COUNT(1). You cannot use * to retrieve
all columns.
• The FROM clause must consist of exactly one object name (mandatory).
• The WHERE clause can include a valid SQL expression to narrow the selection (optional). Use field integration
names as SQL column names.
• The ORDER BY clause can include a valid SQL expression to order the selection (optional). Use field
integration names as SQL column names.
You can use special tokens in your queries such as:
• TODAY for current time
• WEEK for 12PM of last Sunday
• MONTH for 12PM of 1st day of current month
• QUARTER for 12PM of 1st day of current quarter
• YEAR for 12PM of 1st day of current year
• CURR_USER for id of currently logged in user
Object and Field names are case-sensitive, while other components of the SQL query are not.
Use #code suffix to fetch integration codes for picklist fields rather than IDs. See Adding Logic to an Application
for more information.
Syntax
selectQuery(string sessionId, string query, int maxRows);
Parameters
sessionId
A string containing the session ID obtained at log in.
query
SQL SELECT query
maxRows
An integer value representing the maximum number of rows to retrieve (can be configured per
Rollbase instance)
Output
SELECT query wrapped in a StringArr2D
Permissions Required
View permission for the requested object type.
Example
StringArr2D values = binding.selectQuery(sessionId, "SELECT loginName, firstName, lastName
FROM USER ORDER BY lastLogin DESC", 10);
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1355
Chapter 15: Reference
StringArr[] recs = values.getArr();
for (StringArr rec: recs) {
String[] data = rec.getArr();
String loginName = data[0];
String firstName = data[1];
String lastName = data[2];
}
selectValue()
Purpose
Runs an SQL SELECT query on the server and returns a single String value as the result.
The SELECT query used in this method consists of the following parts:
• The SELECT statement expects columns or expressions to be selected (mandatory). Use the field integration
names as SQL column names. You can use expressions such as COUNT(1). You cannot use * to retrieve
all columns.
• The FROM clause must consist of exactly one object name (mandatory).
• The WHERE clause can include a valid SQL expression to narrow the selection (optional). Use field integration
names as SQL column names.
• The ORDER BY clause can include a valid SQL expression to order the selection (optional). Use field
integration names as SQL column names.
You can use special tokens in your queries such as:
• TODAY for current time
• WEEK for 12PM of last Sunday
• MONTH for 12PM of 1st day of current month
• QUARTER for 12PM of 1st day of current quarter
• YEAR for 12PM of 1st day of current year
• CURR_USER for id of currently logged in user
Object and Field names are case-sensitive, while other components of the SQL query are not.
Use #code suffix to fetch integration codes for picklist fields rather than IDs. See Adding Logic to an Application
for more information.
Syntax
selectValue(string sessionId, string query);
Parameters
sessionId
A string containing the session ID obtained at log in.
query
An SQL SELECT query. See the examples described for selectQuery().
1356 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Rollbase SOAP Methods
Output
Single result of SELECT query as string
Permissions Required
View permission for the requested object type.
Example
// Login name of last login user (one value)
String loginName = binding.selectValue(sessionId,
"SELECT loginName FROM USER ORDER BY lastLogin DESC");
setBinaryData()
Purpose
Sets the binary data (file attachment) associated with a particular file field from a specific record.
Syntax
setBinaryData(string sessionId, long id, string fieldName, string contentType,
string suggestedFileName, ByteArr binData);
Parameters
sessionId
A string containing the session ID obtained at log in.
id
A long value containing the record ID.
fieldName
File Field's integration name
contentType
MIME content type of data. For example:
text/html
text/plain
application/pdf
application/msword
application/excel
application/vnd.ms-powerpoint
application/wordperfect5.1
application/rtf
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1357
Chapter 15: Reference
suggestedFileName
Suggested file name (with valid file extension)
binData
File's binary data wrapped in a ByteArr
Output
None
Permissions Required
Edit permission for the requested object type.
Example
// Read binary data
byte[] data;
long id = 123456;
ByteArr binData = new ByteArr(data);
binding.setBinaryData(sessionId, id, "pdfData", "application/pdf", "invoice.pdf", binData);
setDataField()
Purpose
For native Rollbase objects, this method sets the value of a single Field for a specified record.
Note: For external objects (such as those mapped to external tables, to OpenEdge Service objects, or through
a D2C connection), you can use the method, setDataField2() on page 1359.
Syntax
setDataField(string sessionId, string id, DataField df, boolean useIds);
Parameters
sessionId
A string containing the session ID obtained at log in.
id
A long value containing the record ID.
df
A new value for the field wrapped in a DataField container.
1358 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Rollbase SOAP Methods
useIds
A boolean value: if true, use numeric IDs for lookup and picklist values; otherwise, use integration
codes and record names.
Output
None
Permissions Required
Edit permission for the requested object type.
Example
// Populate data Field to be set for existing record
DataField Field = new DataField();
Field.setName("R34567");
Field.setValue("100088,100089");
// Call setDataField API
long id = 123456; // Record id - required
binding.setDataField(sessionId, id, Field, true);
setDataField2()
Purpose
For external objects (such as those mapped to external tables, to OpenEdge Service objects, or through a D2C
connection), this method sets the value of a single Field for a specified record.
Note: For native Rollbase objects, you can use the method, setDataField() on page 1358.
Syntax
setDataField2(string sessionId, String objDefName, String uid, DataField df,
Boolean useIds);
Parameters
sessionId
A string containing the session ID obtained at log in.
objDefName
A string containing the object definition integration name.
uid
A string containing the record ID.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1359
Chapter 15: Reference
df
A new value for the field wrapped in a DataField container.
useIds
A boolean value: if true, use numeric IDs for lookup and picklist values; otherwise, use integration
codes and record names.
Output
None
Permissions Required
Edit permission for the requested object type.
Example
// Populate data Field to be set for existing record
DataField Field = new DataField();
Field.setName("R34567");
Field.setValue("100088,100089");
// Call setDataField2 API
binding.setDataField2(sessionId, "client", "123456", Field, true);
setExchangeRate()
Purpose
Sets the exchange rate between two currencies on a given date.
Syntax
setExchangeRate(string sessionId, string srcCode, string destCode, Calendar date,
double rate);
Parameters
sessionId
A string containing the session ID obtained at log in.
srcCode
The currency code to convert from.
destCode
The currency code to convert to.
date
The Calandar object containing the date.
1360 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Rollbase SOAP Methods
rate
Double containing rate to be set
Output
None
Permissions Required
Manage Exchange Rates permission for the logged-in user
Example
Calendar today = Calendar.getInstance();
today.setTime(new Date());
binding.setExchangeRate(sessionId, "EUR", "USD", today, 1.2823);
setRelationship()
Purpose
For native Rollbase objects, this method assigns an array of related records to the specified record.
Note: For external objects (such as those mapped to external tables, to OpenEdge Service objects, or through
a D2C connection), you can use the method, setRelatedIDs() on page 1362.
Syntax
setRelationship(string sessionId, long id, string relName, LongArr arr);
Parameters
sessionId
A string containing the session ID obtained at log in.
id
A long value containing the record ID.
relName
Relationship's integration name
arr
IDs of related records
Output
None
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1361
Chapter 15: Reference
Permissions Required
Edit permission for the requested object type.
Example
long id = 123456;
long[] arr = new long[] { 100890, 100891 };
binding.setRelationships(sessionId, id, "R1223456", new LongArr(arr));
setRelatedIDs()
Purpose
For external objects (such as those mapped to external tables, to OpenEdge Service objects, or through a D2C
connection), this method assigns an array of related records to the specified record.
Note: For native Rollbase objects, you can use the method, setRelationship() on page 1361.
Syntax
setRelatedIDs(string sessionId, String objDefName, String uid, String relName,
StringArr arr);
Parameters
sessionId
A string containing the session ID obtained at log in.
objDefName
A string containing the object definition integration name.
uid
A string containing the record ID.
relName
Relationship's integration name
arr
IDs of related records
Output
None
Permissions Required
Edit permission for the requested object type.
1362 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Rollbase SOAP Methods
Example
String[] arr = new String[] { "100890", "100891" };
binding.setRelatedIDs(sessionId, "client", "123456", "R1223456", new StringArr(arr));
textSearch()
Purpose
Performs a full-text search in the Rollbase database. The search query has the same syntax used in the
standard Rollbase interface. For more information about search syntax, see Views and Search.
Syntax
textSearch(string sessionId, string query, [string objDefName]);
Parameters
sessionId
A string containing the session ID obtained at log in.
query
Query for full-text search like "John Smith" (see Views and Search for more details)
objDefName
Integration name for selected object definition. This parameter is optional and allows you to narrow
the search to a specified object.
Output
IDs of all records found in the search, returned as LongArr
Example
LongArr arr = binding.textSearch(sessionId, "John Smith", "lead");
long[] ids = arr.getArr();
update()
Purpose
Updates an existing record.
This method only works with native Rollbase objects. To update an external object record, see updateRecord()
on page 1367.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1363
Chapter 15: Reference
Syntax
update(string sessionId, long id, DataFieldArr arr, boolean useIds);
Parameters
sessionId
A string containing the session ID obtained at log in.
id
A long value containing the record ID.
arr
A DataFieldArr array of values for fields of a newly created record. Record ID and auto-numbers
are assigned automatically.
useIds
A boolean value: if true, use numeric IDs for lookup and picklist values; otherwise, use integration
codes and record names.
Output
None
Permissions Required
Edit permission for the requested object type.
Example
// Populate data Fields to be updated for existing record
DataField[] Fields = new DataField[5];
DataField Field = new DataField();
Field.setName("R34567");
Field.setValue("100088,100089");
Fields[0]=Field;
// Call update API
long id = 123456; // Record id - required
binding.update(sessionId, id, new DataFieldArr(Fields), true);
updateArr()
Purpose
Updates array of existing Object records. Note that this method increments the API hits counter for each array
element.
Syntax
updateArr(string sessionId, DataObjArr arr, boolean useIds);
1364 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Rollbase SOAP Methods
Parameters
sessionId
A string containing the session ID obtained at log in.
arr
An Array of DataObj instances with data for existing records. DataObj instances must include
valid record IDs.
useIds
A boolean value: if true, use numeric IDs for lookup and picklist values; otherwise, use integration
codes and record names.
Output
None
Permissions Required
Edit permission for the requested object type.
Example
// Array of transport objects to be sent to updateArr
DataObj[] arr = new DataObj[10];
// Populate data Fields to be updated for record 0
DataField[] Fields = new DataField[5];
DataField Field = new DataField();
Field.setName("amount");
Field.setValue(1000);
Fields[0]=Field;
// Update record 0
DataObj obj = new DataObj();
obj.setId(123456); // Required for update
obj.setObjDefName("lead");
obj.setFields(Fields);
arr[0] = obj;
// Repeat for record 1
// Call updateArr API
binding.updateArr(sessionId, new DataObjArr(arr), false);
updateArrNoAudit()
Purpose
Updates array of existing object records. This method is similar to updateArr, except that it blocks audit records.
This method will increment the API hits counter for each array element.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1365
Chapter 15: Reference
Syntax
updateArrNoAudit(string sessionId, DataObj arr);
Parameters
sessionId
A string containing the session ID obtained at log in.
arr
An Array of DataObj instances with data for existing records. DataObj instances must include
valid record IDs.
useIds
A boolean value: if true, use numeric IDs for lookup and picklist values; otherwise, use integration
codes and record names.
Output
None
Permissions Required
Edit permission for the requested object type.
updateCustomer()
Purpose
Updates a Customer record with the supplied values.
Syntax
updateCustomer(string sessionId, long id, arr, useIds);
Parameters
sessionId
A string containing the session ID obtained at log in.
id
The customer ID.
arr
Values for fields to be updated.
1366 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Rollbase SOAP Methods
useIds
A boolean value: if true, use numeric IDs for lookup and picklist values; otherwise, use integration
codes and record names.
Output
None
Permissions Required
Edit permission for the Customer type.
Example
DataField[] arr = new DataField[1];
arr[0] = getField("companyName", "API Updated Test");
binding.updateCustomer(sessionId, 123456, new DataFieldArr(arr), true);
updateRecord()
Purpose
Updates an existing record.
This method works with external objects (including those mapped to OpenEdge services) and native Rollbase
objects.
Syntax
updateRecord(string sessionId, string objDefName, string uid, DataFieldArr arr, boolean
useIds);
Parameters
sessionId
A string containing the session ID obtained at log in.
objDefName
A string containing the object definition integration name.
uid
A string containing the record ID.
arr
A DataFieldArr array of values for fields of a newly created record. Record ID and auto-numbers
are assigned automatically.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1367
Chapter 15: Reference
useIds
A boolean value: if true, use numeric IDs for lookup and picklist values; otherwise, use integration
codes and record names.
Output
None.
Permissions Required
Edit permission for the requested object type.
1368 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
16
Getting help
If you need help with Rollbase, try the following resources:
• For help with getting started on Rollbase, see the videos posted on:
https://www.progress.com/video?product=progress-rollbase.
• For How-To-Videos on Rollbase, visit https://www.progress.com/video/how-to?product=progress-rollbase.
• For help with technical issues, see The Progress Technical Users Community Forum:
https://community.progress.com/community_groups/rollbase/.
• For knowledge base articles, visit http://knowledgebase.progress.com and select Rollbase as the Product
Group.
• For customer service, billing, and licensing questions, visit https://www.progress.com/company/contact.
• For Tutorial and quick learning, visit the Quick Start Tutorial page
https://documentation.progress.com/output/rb/tutorial-qs/index.html#page/rollbasetutorial%2Fwelcome-to-the-quick-start-tutorial!.html%23.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1369
Chapter 16: Getting help
1370 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
17
Third-party Acknowledgements
The following notice applies to the Rollbase private cloud.
For details, see the following topics:
• Rollbase Private Cloud Third-party Acknowledgements
Rollbase Private Cloud Third-party Acknowledgements
Release Notes - Documentation Third-Party Acknowledgements
One or more products in the Progress Rollbase Private Cloud v5.3 release includes third party components
covered by licenses that require that the following documentation notices be provided. If changes in third party
components occurred for the current release of the Product, the following Third-Party Acknowledgements may
contain notice updates to any earlier versions provided in documentation or a README file.
Progress Rollbase Private Cloud v5.3 incorporates Apache Commons Discovery v0.2. Such technology is
subject to the following terms and conditions: The Apache Software License, Version 1.1 - Copyright (c)
1999-2001 The Apache Software Foundation. All rights reserved.
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the
following conditions are met:
1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following
disclaimer.
2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the
following disclaimer in the documentation and/or other materials provided with the distribution.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1371
Chapter 17: Third-party Acknowledgements
3. The end-user documentation included with the redistribution, if any, must include the following
acknowlegement:
"This product includes software developed by the Apache Software Foundation (http://www.apache.org/)."
Alternately, this acknowlegement may appear in the software itself, if and wherever such third-party
acknowlegements normally appear.
4. The names "The Jakarta Project", "Commons", and "Apache Software Foundation" must not be used to
endorse or promote products derived from this software without prior written permission. For written permission,
please contact [email protected].
5. Products derived from this software may not be called "Apache" nor may "Apache" appear in their names
without prior written permission of the Apache Group.
THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED WARRANTIES, INCLUDING,
BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION
OR ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY,
OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE
GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
====================================================================
This software consists of voluntary contributions made by many individuals on behalf of the Apache Software
Foundation. For more information on the Apache Software Foundation, please see <http://www.apache.org/>.
Progress Rollbase Private Cloud v5.3 incorporates ESAPI v2.1.0.1. Such technology is subject to the following
terms and conditions: The BSD License
Copyright (c) 2007, The OWASP Foundation All rights reserved.
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the
following conditions are met:
Redistributions of source code must retain the above copyright notice, this list of conditions and the following
disclaimer.
Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following
disclaimer in the documentation and/or other materials provided with the distribution.
Neither the name of the OWASP Foundation nor the names of its contributors may be used to endorse or
promote products derived from this software without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY
EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT
SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY
WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
Progress Rollbase Private Cloud v5.3 incorporates Jaxen-1.1.jar v1.1. Such technology is subject to the following
terms and conditions:
Copyright 2003-2006 The Werken Company. All Rights Reserved.
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the
following conditions are met:
1372 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Rollbase Private Cloud Third-party Acknowledgements
Redistributions of source code must retain the above copyright notice, this list of conditions and the following
disclaimer.
Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following
disclaimer in the documentation and/or other materials provided with the distribution.
Neither the name of the Jaxen Project nor the names of its contributors may be used to endorse or promote
products derived from this software without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY
OF SUCH DAMAGE.
Progress Rollbase Private Cloud v5.3 incorporates Jdom.jar v1.0. Such technology is subject to the following
terms and conditions: Copyright (C) 2000-2004 Jason Hunter & Brett McLaughlin. All rights reserved.
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the
following conditions are met:
1. Redistributions of source code must retain the above copyright notice, this list of conditions, and the following
disclaimer.
2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions, and the
disclaimer that follows these conditions in the documentation and/or other materials provided with the distribution.
3. The name "JDOM" must not be used to endorse or promote products derived from this software without prior
written permission. For written permission, please contact <request_AT_jdom_DOT_org>.
4. Products derived from this software may not be called "JDOM", nor may "JDOM" appear in their name,
without prior written permission from the JDOM Project Management <request_AT_jdom_DOT_org>.
In addition, we request (but do not require) that you include in the end-user documentation provided with the
redistribution and/or in the software itself an acknowledgement equivalent to the following:
"This product includes software developed by the JDOM Project (http://www.jdom.org/)."
Alternatively, the acknowledgment may be graphical using the logos available at
http://www.jdom.org/images/logos.
THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED WARRANTIES, INCLUDING,
BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE JDOM AUTHORS OR THE PROJECT
CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE
GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
This software consists of voluntary contributions made by many individuals on behalf of the JDOM Project and
was originally created by Jason Hunter <jhunter_AT_jdom_DOT_org> and Brett McLaughlin
<brett_AT_jdom_DOT_org>. For more information on the JDOM Project, please see <http://www.jdom.org/>.
Progress Rollbase Private Cloud v5.3 incorporates lsimplecaptcha.jar v1.2.1. Such technology is subject to
the following terms and conditions: Copyright (c) 2008, James Childers All rights reserved.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1373
Chapter 17: Third-party Acknowledgements
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the
following conditions are met:
o Redistributions of source code must retain the above copyright notice, this list of conditions and the following
disclaimer.
o Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the
following disclaimer in the documentation and/or other materials provided with the distribution.
o Neither the name of SimpleCaptcha nor the names of its contributors may be used to endorse or promote
products derived from this software without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY
EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT
SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY
WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
Progress Rollbase Private Cloud v5.3 incorporates Apache dom4j v1.6.1. Such technology is subject to the
following terms and conditions: Copyright 2001-2005 (C) MetaStuff, Ltd. All Rights Reserved. Redistribution
and use of this software and associated documentation ("Software"), with or without modification, are permitted
provided that the following conditions are met:
1. Redistributions of source code must retain copyright statements and notices. Redistributions must also
contain a copy of this document.
2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the
following disclaimer in the documentation and/or other materials provided with the distribution.
3. The name "DOM4J" must not be used to endorse or promote products derived from this Software without
prior written permission of MetaStuff, Ltd. For written permission, please contact [email protected].
4. Products derived from this Software may not be called "DOM4J" nor may "DOM4J" appear in their names
without prior written permission of MetaStuff, Ltd. DOM4J is a registered trademark of MetaStuff, Ltd.
5. Due credit should be given to the DOM4J Project - http://www.dom4j.org
THIS SOFTWARE IS PROVIDED BY METASTUFF, LTD. AND CONTRIBUTORS ``AS IS'' AND ANY
EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT
SHALL METASTUFF, LTD. OR ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY
WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
Progress Rollbase Private Cloud v5.3 incorporates icu4j v61.1. Such technology is subject to the following
terms and conditions:
ICU License - ICU 1.8.1 and later - COPYRIGHT AND PERMISSION NOTICE
Copyright (c) 1995-2014 International Business Machines Corporation and others. All rights reserved.
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated
documentation files (the "Software"), to deal in the Software without restriction, including without limitation the
rights to use, copy, modify, merge, publish, distribute, and/or sell copies of the Software, and to permit persons
to whom the Software is furnished to do so, provided that the above copyright notice(s) and this permission
notice appear in all copies of the Software and that both the above copyright notice(s) and this permission
notice appear in supporting documentation.
1374 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Rollbase Private Cloud Third-party Acknowledgements
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
PARTICULAR PURPOSE AND NONINFRINGEMENT OF THIRD PARTY RIGHTS. IN NO EVENT SHALL
THE COPYRIGHT HOLDER OR HOLDERS INCLUDED IN THIS NOTICE BE LIABLE FOR ANY CLAIM, OR
ANY SPECIAL INDIRECT OR CONSEQUENTIAL DAMAGES, OR ANY DAMAGES WHATSOEVER RESULTING
FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE
OF THIS SOFTWARE.
Except as contained in this notice, the name of a copyright holder shall not be used in advertising or otherwise
to promote the sale, use or other dealings in this Software without prior written authorization of the copyright
holder.
All trademarks and registered trademarks mentioned herein are the property of their respective owners.
Third-Party Software Licenses
This section contains third-party software notices and/or additional terms for licensed third-party software
components included within ICU libraries.
1. Unicode Data Files and Software
COPYRIGHT AND PERMISSION NOTICE
Copyright © 1991-2014 Unicode, Inc. All rights reserved.
Distributed under the Terms of Use in
http://www.unicode.org/copyright.html.
Permission is hereby granted, free of charge, to any person obtaining a copy of the Unicode data files and any
associated documentation (the "Data Files") or Unicode software and any associated documentation (the
"Software") to deal in the Data Files or Software without restriction, including without limitation the rights to
use, copy, modify, merge, publish, distribute, and/or sell copies of the Data Files or Software, and to permit
persons to whom the Data Files or Software are furnished to do so, provided that (a) this copyright and permission
notice appear with all copies of the Data Files or Software, (b) this copyright and permission notice appear in
associated documentation, and (c) there is clear notice in each modified Data File or in the Software as well
as in the documentation associated with the Data File(s) or Software that the data or software has been modified.
THE DATA FILES AND SOFTWARE ARE PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT OF THIRD PARTY RIGHTS. IN NO
EVENT SHALL THE COPYRIGHT HOLDER OR HOLDERS INCLUDED IN THIS NOTICE BE LIABLE FOR
ANY CLAIM, OR ANY SPECIAL INDIRECT OR CONSEQUENTIAL DAMAGES, OR ANY DAMAGES
WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF
CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH
THE USE OR PERFORMANCE OF THE DATA FILES OR SOFTWARE.
Except as contained in this notice, the name of a copyright holder shall not be used in advertising or otherwise
to promote the sale, use or other dealings in these Data Files or Software without prior written authorization of
the copyright holder.
2. Chinese/Japanese Word Break Dictionary Data (cjdict.txt)
The Google Chrome software developed by Google is licensed under the BSD license. Other software included
in this distribution is provided under other licenses, as set forth below.
The BSD License
http://opensource.org/licenses/bsd-license.php
Copyright (C) 2006-2008, Google Inc.
All rights reserved.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1375
Chapter 17: Third-party Acknowledgements
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the
following conditions are met:
Redistributions of source code must retain the above copyright notice, this list of conditions and the following
disclaimer.
Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following
disclaimer in the documentation and/or other materials provided with the distribution.
Neither the name of Google Inc. nor the names of its contributors may be used to endorse or promote products
derived from this software without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY
EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT
SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY
WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
The word list in cjdict.txt are generated by combining three word lists listed below with further processing for
compound word breaking. The frequency is generated with an iterative training against Google web corpora.
Libtabe (Chinese)
- https://sourceforge.net/project/?group_id=1519
- Its license terms and conditions are shown below.
IPADIC (Japanese)
- http://chasen.aist-nara.ac.jp/chasen/distribution.html
- Its license terms and conditions are shown below.
---------COPYING.libtabe ---- BEGIN--------------------/*
Copyrighy (c) 1999 TaBE Project.
Copyright (c) 1999 Pai-Hsiang Hsiao.
All rights reserved.
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the
following conditions are met:
. Redistributions of source code must retain the above copyright notice, this list of conditions and the following
disclaimer.
. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following
disclaimer in the documentation and/or other materials provided with the distribution.
. Neither the name of the TaBE Project nor the names of its contributors may be used to endorse or promote
products derived from this software without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY
EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT
SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY
WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
1376 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Rollbase Private Cloud Third-party Acknowledgements
Copyright (c) 1999 Computer Systems and Communication Lab,
Institute of Information Science, Academia Sinica.
All rights reserved.
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the
following conditions are met:
. Redistributions of source code must retain the above copyright notice, this list of conditions and the following
disclaimer.
. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following
disclaimer in the documentation and/or other materials provided with the distribution.
. Neither the name of the Computer Systems and Communication Lab nor the names of its contributors may
be used to endorse or promote products derived from this software without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY
EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT
SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY
WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
Copyright 1996 Chih-Hao Tsai @ Beckman Institute, University of Illinois [email protected]
http://casper.beckman.uiuc.edu/~c-tsai4
---------------COPYING.libtabe-----END-------------------------------
---------------COPYING.ipadic-----BEGIN------------------------------ Copyright 2000, 2001, 2002, 2003 Nara Institute
of Science and Technology. All Rights Reserved.
Use, reproduction, and distribution of this software is permitted.
Any copy of this software, whether in its original form or modified, must include both the above copyright notice
and the following paragraphs.
Nara Institute of Science and Technology (NAIST), the copyright holders, disclaims all warranties with regard
to this software, including all implied warranties of merchantability and fitness, in no event shall NAIST be liable
for any special, indirect or consequential damages or any damages whatsoever resulting from loss of use, data
or profits, whether in an action of contract, negligence or other tortuous action, arising out of or in connection
with the use or performance of this software.
A large portion of the dictionary entries originate from ICOT Free Software. The following conditions for ICOT
Free Software applies to the current dictionary as well.
Each User may also freely distribute the Program, whether in its original form or modified, to any third party or
parties, PROVIDED that the provisions of Section 3 ("NO WARRANTY") will ALWAYS appear on, or be attached
to, the Program, which is distributed substantially in the same form as set out herein and that such intended
distribution, if actually made, will neither violate or otherwise contravene any of the laws and regulations of the
countries having jurisdiction over the User or the intended distribution itself.
NO WARRANTY
The program was produced on an experimental basis in the course of the research and development conducted
during the project and is provided to users as so produced on an experimental basis. Accordingly, the program
is provided without any warranty whatsoever, whether express, implied, statutory or otherwise. The term
"warranty" used herein includes, but is not limited to, any warranty of the quality, performance, merchantability
and fitness for a particular purpose of the program and the nonexistence of any infringement or violation of any
right of any third party.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1377
Chapter 17: Third-party Acknowledgements
Each user of the program will agree and understand, and be deemed to have agreed and understood, that
there is no warranty whatsoever for the program and, accordingly, the entire risk arising from or otherwise
connected with the program is assumed by the user.
Therefore, neither ICOT, the copyright holder, or any other organization that participated in or was otherwise
related to the development of the program and their respective officials, directors, officers and other employees
shall be held liable for any and all damages, including, without limitation, general, special, incidental and
consequential damages, arising out of or otherwise in connection with the use or inability to use the program
or any product, material or result produced or otherwise obtained by using the program, regardless of whether
they have been advised of, or otherwise had knowledge of, the possibility of such damages at any time during
the project or thereafter. Each user will be deemed to have agreed to the foregoing by his or her commencement
of use of the program. The term "use" as used herein includes, but is not limited to, the use, modification,
copying and distribution of the program and the production of secondary products from the program.
In the case where the program, whether in its original form or modified, was distributed or delivered to or
received by a user from any person, organization or entity other than ICOT, unless it makes or grants
independently of ICOT any specific warranty to the user in writing, such person, organization or entity, will also
be exempted from and not be held liable to the user for any such damages as noted above as far as the program
is concerned.
---------------COPYING.ipadic-----END--------------------------------
3. Lao Word Break Dictionary Data (laodict.txt)
Copyright (c) 2013 International Business Machines Corporation and others. All Rights Reserved.
Project: http://code.google.com/p/lao-dictionary/
Dictionary: http://lao-dictionary.googlecode.com/git/Lao-Dictionary.txt
License: http://lao-dictionary.googlecode.com/git/Lao-Dictionary-LICENSE.txt copied below)
This file is derived from the above dictionary, with slight modifications.
---------------------------------------------------------------------Copyright (C) 2013 Brian Eugene Wilson, Robert Martin
Campbell.
All rights reserved.
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the
following conditions are met:
Redistributions of source code must retain the above copyright notice, this list of conditions and the following
disclaimer. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and
the following disclaimer in the documentation and/or other materials provided with the distribution.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY
EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT
SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY
WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
---------------------------------------------------------------------
4. Burmese Word Break Dictionary Data (burmesedict.txt)
Copyright (c) 2014 International Business Machines Corporation and others. All Rights Reserved.
This list is part of a project hosted at:
github.com/kanyawtech/myanmar-karen-word-lists
1378 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Rollbase Private Cloud Third-party Acknowledgements
--------------------------------------------------------------------- Copyright (c) 2013, LeRoy Benjamin Sharon
All rights reserved.
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the
following conditions are met:
Redistributions of source code must retain the above copyright notice, this list of conditions and the following
disclaimer.
Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following
disclaimer in the documentation and/or other materials provided with the distribution.
Neither the name Myanmar Karen Word Lists, nor the names of its contributors may be used to endorse or
promote products derived from this software without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY
EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT
SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY
WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
---------------------------------------------------------------------
5. Time Zone Database
ICU uses the public domain data and code derived from Time Zone Database for its time zone support. The
ownership of the TZ database is explained in BCP 175: Procedure for Maintaining the Time Zone Database
section 7.
7. Database Ownership
The TZ database itself is not an IETF Contribution or an IETF document. Rather it is a pre-existing and regularly
updated work that is in the public domain, and is intended to remain in the public domain. Therefore, BCPs 78
[RFC5378] and 79 [RFC3979] do not apply to the TZ Database or contributions that individuals make to it.
Should any claims be made and substantiated against the TZ Database, the organization that is providing the
IANA Considerations defined in this RFC, under the memorandum of understanding with the IETF, currently
ICANN, may act in accordance with all competent court orders. No ownership claims will be made by ICANN
or the IETF Trust on the database or the code. Any person making a contribution to the database or code
waives all rights to future claims in that contribution or in the TZ Database.
Progress Rollbase Private Cloud v5.3 incorporates HSQL Development Group HyperSQL DB v2.3.3. Such
technology is subject to the following terms and conditions:
COPYRIGHTS AND LICENSES (based on BSD License)
For work developed by the HSQL Development Group:
Copyright (c) 2001-2016, The HSQL Development Group All rights reserved.
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the
following conditions are met:
Redistributions of source code must retain the above copyright notice, this list of conditions and the following
disclaimer.
Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following
disclaimer in the documentation and/or other materials provided with the distribution.
Neither the name of the HSQL Development Group nor the names of its contributors may be used to endorse
or promote products derived from this software without specific prior written permission.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1379
Chapter 17: Third-party Acknowledgements
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY
EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT
SHALL HSQL DEVELOPMENT GROUP, HSQLDB.ORG, OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
THE POSSIBILITY OF SUCH DAMAGE.
For work originally developed by the Hypersonic SQL Group:
Copyright (c) 1995-2000 by the Hypersonic SQL Group. All rights reserved.
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the
following conditions are met:
Redistributions of source code must retain the above copyright notice, this list of conditions and the following
disclaimer.
Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following
disclaimer in the documentation and/or other materials provided with the distribution.
Neither the name of the Hypersonic SQL Group nor the names of its contributors may be used to endorse or
promote products derived from this software without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY
EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT
SHALL THE HYPERSONIC SQL GROUP, OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY
WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
This software consists of voluntary contributions made by many individuals on behalf of the Hypersonic SQL
Group.
Progress Rollbase Private Cloud v5.3 incorporates ESAPI v2.1.0 (as part of Progress AppServer (PAS) Core
v2.0). This technology is subject to the following terms and conditions:
The BSD License
Copyright (c) 2007, The OWASP Foundation All rights reserved.
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the
following conditions are met:
Redistributions of source code must retain the above copyright notice, this list of conditions and the following
disclaimer.
Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following
disclaimer in the documentation and/or other materials provided with the distribution.
Neither the name of the OWASP Foundation nor the names of its contributors may be used to endorse or
promote products derived from this software without specific prior written permission.
1380 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Rollbase Private Cloud Third-party Acknowledgements
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY
EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT
SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY
WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
Progress Rollbase Private Cloud v5.3 incorporates ThreeTen backport v1.3.6. This technology is subject to
the following terms and conditions:
Copyright (c) 2007-present, Stephen Colebourne & Michael Nascimento Santos All rights reserved.
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the
following conditions are met:
Redistributions of source code must retain the above copyright notice, this list of conditions and the following
disclaimer.
Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following
disclaimer in the documentation and/or other materials provided with the distribution.
Neither the name of JSR-310 nor the names of its contributors may be used to endorse or promote products
derived from this software without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY
EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT
SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY
WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
Progress Rollbase Private Cloud v5.3 incorporates Adobe XMP Core v5.1.2. This technology is subject to the
following terms and conditions: The BSD License
Copyright (c) 2009, Adobe Systems Incorporated All rights reserved.
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the
following conditions are met:
* Redistributions of source code must retain the above copyright notice, this list of conditions and the following
disclaimer.
* Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the
following disclaimer in the documentation and/or other materials provided with the distribution.
* Neither the name of Adobe Systems Incorporated, nor the names of its contributors may be used to endorse
or promote products derived from this software without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY
EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
OF MERCHANT ABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT
SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY
WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1381
Chapter 17: Third-party Acknowledgements
Progress Rollbase Private Cloud v5.3 incorporates OWASP Foundation Java Encoder v1.2.1. This technology
is subject to the following terms and conditions:
Copyright (c) 2015 OWASP.
All rights reserved.
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the
following conditions are met:
* Redistributions of source code must retain the above copyright notice, this list of conditions and the following
disclaimer.
* Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the
following disclaimer in the documentation and/or other materials provided with the distribution.
* Neither the name of the OWASP nor the names of its contributors may be used to endorse or promote products
derived from this software without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY
EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT
SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY
WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
Progress Rollbase Private Cloud v5.3 incorporates OMax Ogden electron-packager v8.7.2. This technology
is subject to the following terms and conditions:
Copyright (c) 2015 Max Ogden and other contributors
All rights reserved.
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the
following conditions are met:
* Redistributions of source code must retain the above copyright notice, this list of conditions and the following
disclaimer.
* Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the
following disclaimer in the documentation and/or other materials provided with the distribution.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY
EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT
SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY
WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
Progress Rollbase Private Cloud v5.3 incorporates Nginx Inc. Nginx v1.11.10. This technology is subject to
the following terms and conditions:
Copyright (C) 2002-2017 Igor Sysoev
Copyright (C) 2011-2017 Nginx, Inc.
All rights reserved.
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the
following conditions are met:
1382 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Rollbase Private Cloud Third-party Acknowledgements
1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following
disclaimer.
2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the
following disclaimer in the documentation and/or other materials provided with the distribution.
THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND ANY EXPRESS
OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT
SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY
WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
Progress Rollbase Private Cloud v5.3 incorporates Terence Parr Another Tool for Language Recognition
(ANTLR) v4.5. This technology is subject to the following terms and conditions:
ANTLR 4 License
[The BSD License]
Copyright (c) 2012 Terence Parr and Sam Harwell
All rights reserved.
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the
following conditions are met:
Redistributions of source code must retain the above copyright notice, this list of conditions and the following
disclaimer.
Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following
disclaimer in the documentation and/or other materials provided with the distribution.
Neither the name of the author nor the names of its contributors may be used to endorse or promote products
derived from this software without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY
EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT
SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY
WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
Progress Rollbase Private Cloud v5.3 incorporates Zhang, Yuexiang (xfeep) Nginx clojure v0.4.4. This technology
is subject to the following terms and conditions:
Copyright © 2013-2017 Zhang, Yuexiang (xfeep) and released under the BSD 3-Clause license.
This program uses:
Re-rooted ASM bytecode engineering library which is distributed under the BSD 3-Clause license
Modified Continuations Library Written by Matthias Mann is distributed under the BSD 3-Clause license
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the
following conditions are met:
1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following
disclaimer.
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1383
Chapter 17: Third-party Acknowledgements
2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the
following disclaimer in the documentation and/or other materials provided with the distribution.
3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote
products derived from this software without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY
EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT
SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY
WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
Progress Rollbase Private Cloud v5.3 incorporates JZlib v1.1.3. This technology is subject to the following
terms and conditions:
Copyright (c) 2000-2011 ymnk, JCraft,Inc. All rights reserved.
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:
1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following
disclaimer.
2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the
following disclaimer in the documentation and/or other materials provided with the distribution.
3. The names of the authors may not be used to endorse or promote products derived from this software without
specific prior written permission.
THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED WARRANTIES, INCLUDING,
BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL JCRAFT, INC. OR ANY CONTRIBUTORS
TO THIS SOFTWARE BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY,
OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE
GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
Progress Rollbase Private Cloud v5.3 incorporates Mozilla JS v1.7R4. The Original Code is Rhino code,
released May 6, 1999. The Initial Developer of the Original Code is Netscape Communications Corporation.
Portions created by the Initial Developer are Copyright (C) 1997-1999 the Initial Developer. All Rights Reserved.
License for portions of the Rhino debugger
The majority of the technology is subject to the terms and conditions of the Mozilla Public License Version 2.0
Additionally, some files (currently the contents of toolsrc/org/mozilla/javascript/tools/debugger/treetable/) are
available under the following license:
Copyright 1997, 1998 Sun Microsystems, Inc. All Rights Reserved.
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the
following conditions are met:
- Redistributions of source code must retain the above copyright notice, this list of conditions and the following
disclaimer.
- Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following
disclaimer in the documentation and/or other materials provided with the distribution.
1384 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
Rollbase Private Cloud Third-party Acknowledgements
- Neither the name of Sun Microsystems nor the names of its contributors may be used to endorse or promote
products derived from this software without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY
EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT
SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY
WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
Updated: 9/20/2018
Rollbase: Progress® Rollbase® User's Guide: Version 5.3 1385
Chapter 17: Third-party Acknowledgements
1386 Rollbase: Progress® Rollbase® User's Guide: Version 5.3
You might also like
- .NET MAUI Cookbook: Build a full-featured app swiftly with MVVM, CRUD, AI, authentication, real-time updates, and moreFrom Everand.NET MAUI Cookbook: Build a full-featured app swiftly with MVVM, CRUD, AI, authentication, real-time updates, and moreNo ratings yet
- LOGIQ-P10-XDclear Brochure Giu Glob jb03032xx March2021No ratings yetLOGIQ-P10-XDclear Brochure Giu Glob jb03032xx March20215 pages
- Art Models 8 - Practical Poses For The Working Artist (PDFDrive)86% (7)Art Models 8 - Practical Poses For The Working Artist (PDFDrive)196 pages
- Blog Smarter, Not Harder: SEO, Blogging, and AI Strategies to Skyrocket Your TrafficFrom EverandBlog Smarter, Not Harder: SEO, Blogging, and AI Strategies to Skyrocket Your TrafficNo ratings yet
- Advanced Multiplayer Game Development with Ureal Engine 5: A Comprehensive Guide to C++ ScriptingFrom EverandAdvanced Multiplayer Game Development with Ureal Engine 5: A Comprehensive Guide to C++ ScriptingNo ratings yet
- Cybersecurity for Executives: A Guide to Protecting Your BusinessFrom EverandCybersecurity for Executives: A Guide to Protecting Your BusinessNo ratings yet
- The Modern Vulkan Cookbook: A practical guide to 3D graphics and advanced real-time rendering techniques in VulkanFrom EverandThe Modern Vulkan Cookbook: A practical guide to 3D graphics and advanced real-time rendering techniques in VulkanNo ratings yet
- JAVA PROGRAMMING FOR BEGINNERS: Master Java Fundamentals and Build Your Own Applications (2023 Crash Course)From EverandJAVA PROGRAMMING FOR BEGINNERS: Master Java Fundamentals and Build Your Own Applications (2023 Crash Course)No ratings yet
- Microsoft Power Pages in Action: Accelerate your low-code journey with functional-rich web apps using Power PagesFrom EverandMicrosoft Power Pages in Action: Accelerate your low-code journey with functional-rich web apps using Power PagesNo ratings yet
- React.js for A Beginners Guide : From Basics to Advanced - A Comprehensive Guide to Effortless Web Development for Beginners, Intermediates, and ExpertsFrom EverandReact.js for A Beginners Guide : From Basics to Advanced - A Comprehensive Guide to Effortless Web Development for Beginners, Intermediates, and ExpertsNo ratings yet
- Ultimate Nuxt.js for Full-Stack Web Applications: Build Production-Grade Server-Side Rendering (SSR) and Static-Site Generated (SSG) Vue.js Applications Using Nuxt.js, Node.js, and Composition API (English Edition)From EverandUltimate Nuxt.js for Full-Stack Web Applications: Build Production-Grade Server-Side Rendering (SSR) and Static-Site Generated (SSG) Vue.js Applications Using Nuxt.js, Node.js, and Composition API (English Edition)No ratings yet
- The Linux Terminal for Advanced Users - The Command Line Made Easy: First EditionFrom EverandThe Linux Terminal for Advanced Users - The Command Line Made Easy: First EditionNo ratings yet
- Research And Development Of A Secure Mobile Software Ridesharing Application For United States Military And Department Of Defense EmployeesFrom EverandResearch And Development Of A Secure Mobile Software Ridesharing Application For United States Military And Department Of Defense EmployeesNo ratings yet
- CAN Bus for Beginners: A Practical Guide to Automotive NetworkingFrom EverandCAN Bus for Beginners: A Practical Guide to Automotive NetworkingNo ratings yet
- Cloud Native Apps on Google Cloud Platform: Use Serverless, Microservices and Containers to Rapidly Build and Deploy Apps on Google CloudFrom EverandCloud Native Apps on Google Cloud Platform: Use Serverless, Microservices and Containers to Rapidly Build and Deploy Apps on Google CloudNo ratings yet
- Securing ChatGPT: Best Practices for Protecting Sensitive Data in AI Language ModelsFrom EverandSecuring ChatGPT: Best Practices for Protecting Sensitive Data in AI Language ModelsNo ratings yet
- VMware vRealize Orchestrator Essentials: Get hands-on experience with vRealize Orchestrator and automate your VMware environmentFrom EverandVMware vRealize Orchestrator Essentials: Get hands-on experience with vRealize Orchestrator and automate your VMware environmentNo ratings yet
- JavaScript Design Patterns: Deliver fast and efficient production-grade JavaScript applications at scaleFrom EverandJavaScript Design Patterns: Deliver fast and efficient production-grade JavaScript applications at scaleNo ratings yet
- Active Directory Administration Cookbook: Actionable, proven solutions to identity management and authentication on servers and in the cloudFrom EverandActive Directory Administration Cookbook: Actionable, proven solutions to identity management and authentication on servers and in the cloudNo ratings yet
- Welcome To Progress® V9.1E and Webspeed® V3.1E PDF DocumentationNo ratings yetWelcome To Progress® V9.1E and Webspeed® V3.1E PDF Documentation4 pages
- progress datadirect rest connector guideNo ratings yetprogress datadirect rest connector guide172 pages
- S. A. Ahsan Rajon: S/O: M. A. Khalil RES: 322. Khan-Jahan Ali Road, Shantidham More, Khulna-9100. CellNo ratings yetS. A. Ahsan Rajon: S/O: M. A. Khalil RES: 322. Khan-Jahan Ali Road, Shantidham More, Khulna-9100. Cell7 pages
- Review of Various Software Cost Estimation TechniqNo ratings yetReview of Various Software Cost Estimation Techniq5 pages
- Download Complete (Ebook) JavaScript for Sound Artists: Learn to Code with the Web Audio API, 2nd ed. by William Turner, Steve Leonard ISBN 9781003201496, 1003201490 PDF for All Chapters100% (8)Download Complete (Ebook) JavaScript for Sound Artists: Learn to Code with the Web Audio API, 2nd ed. by William Turner, Steve Leonard ISBN 9781003201496, 1003201490 PDF for All Chapters72 pages
- Apple - The Objective-C.programming Language100% (1)Apple - The Objective-C.programming Language15 pages
- Underwater Communication Using LI-FI Technology: Names of The Students 2. Aviraj Shejawal 3. Dharyashil WaghchaureNo ratings yetUnderwater Communication Using LI-FI Technology: Names of The Students 2. Aviraj Shejawal 3. Dharyashil Waghchaure19 pages
- Performance Evaluation of MmWave in 5G Networks100% (1)Performance Evaluation of MmWave in 5G Networks89 pages
- GATE Computer Network Previous Year QuestionsNo ratings yetGATE Computer Network Previous Year Questions54 pages
- 10 Tools To Make A Bootable USB From An ISO FileNo ratings yet10 Tools To Make A Bootable USB From An ISO File10 pages
- RAMI 4.0: An Architectural Model For Industrie 4.0No ratings yetRAMI 4.0: An Architectural Model For Industrie 4.031 pages
