Rollbase User Guide

® ®
Progress Rollbase User's Guide

Contents
Table of Contents
Copyright...........................................................................................................................17
Chapter 1: Introduction to Progress Rollbase..........................................19

Supported browsers and platforms.......................................................................................................24
Obtaining an account............................................................................................................................24
Logging in...................................................................................................................................24
Updating your profile and logging out........................................................................................25
Selecting and modifying your security questions.......................................................................25
Switching tenants.......................................................................................................................26
Basic Rollbase concepts.......................................................................................................................27
Navigating the Rollbase environment...................................................................................................28
Application page components....................................................................................................32
Setup and setup page components...........................................................................................40
The Rollbase application............................................................................................................44
Search........................................................................................................................................44
Printing and PDF generation......................................................................................................50
Learn with hands-on exercises.............................................................................................................53
Sample applications..............................................................................................................................55
Chapter 2: What's new in this release........................................................57

What's New in Rollbase 4.5.8...............................................................................................................58
What's new in Rollbase 4.5...................................................................................................................59
4.5 User interface-related changes............................................................................................59
4.5 Security and authentication-related features........................................................................60
4.5 API-related changes.............................................................................................................61
4.5 Private Cloud changes.........................................................................................................65
What's new in Rollbase4.4.4.................................................................................................................67
4.4.4 Private Cloud changes......................................................................................................67
What's new in Rollbase 4.4...................................................................................................................68
4.4 Integration with Progress Corticon rules decision service...................................................69
4.4 User interface-related changes............................................................................................70
4.4 New and improved editing capabilities.................................................................................81
4.4 Security and authentication-related features........................................................................96
4.4 Private Cloud changes.......................................................................................................100
4.4 API-related changes...........................................................................................................102
4.4 Improved Formula debugging............................................................................................104
4.4 Miscellaneous ...................................................................................................................106
What's new in Rollbase 4.3.1..............................................................................................................109
What's new in Rollbase 4.3.................................................................................................................112
Rollbase: Progress® Rollbase® User's Guide: Version 4.5 3

Contents

User interface improvements...................................................................................................148
Migrating original ID generation to GUID.................................................................................178
Upgrading Private Cloud to Version 4.X.............................................................................................235
Chapter 3: Designing a Rollbase application..........................................239

Application foundation.........................................................................................................................241
Object definition overview........................................................................................................242
Object attributes.......................................................................................................................243
Relationships............................................................................................................................245
Business logic and customizing the user experience.........................................................................245
Rollbase user interface components........................................................................................245
Setting up accounts for testing............................................................................................................266
Distribution options.............................................................................................................................266
Chapter 4: Laying the foundation.............................................................269

Getting started with the Quick Create wizard......................................................................................270
Creating and managing applications...................................................................................................273
Creating an application your way.............................................................................................273
Editing applications..................................................................................................................274
Deleting an application.............................................................................................................290
Installing applications...............................................................................................................290
Creating and managing objects, fields, and relationships...................................................................297
Creating a new object definition...............................................................................................298
Creating a tab...........................................................................................................................299
Viewing and editing an object definition...................................................................................301
Deleting an object definition.....................................................................................................311
Views...................................................................................................................................................312
View controls............................................................................................................................312
Editing a view component........................................................................................................315
Setting the default view on a record list page..........................................................................316
Relationships between objects...........................................................................................................317
Global relationship lookup field properties...............................................................................318
Changing lookup field behavior................................................................................................318
4 Rollbase: Progress® Rollbase® User's Guide: Version 4.5

Contents
Restricting records for lookup fields.........................................................................................321

Related records components...................................................................................................323
Related grid controls................................................................................................................323
Orphan records........................................................................................................................325
Working with records...........................................................................................................................325
Cloning records........................................................................................................................326
Protecting records....................................................................................................................328
Converting records...................................................................................................................329
Comparing and merging records..............................................................................................334
Auditing....................................................................................................................................338
Sending email..........................................................................................................................340
Transferring owners.................................................................................................................343
Updating multiple records........................................................................................................343
Tagging records........................................................................................................................346
Chapter 5: Adding business logic ...........................................................349

Working with templates.......................................................................................................................350
HTML and Script components..................................................................................................351
Adding template fields and integration links to an object.........................................................354
Template token syntax.............................................................................................................354
Iterating through records..........................................................................................................362
Using EVAL blocks...................................................................................................................364
Creating a record name template.............................................................................................364
Email templates........................................................................................................................365
Document templates................................................................................................................366
Communication logs.................................................................................................................371
Localization..............................................................................................................................372
New record template................................................................................................................372
Right to left support in templates..............................................................................................372
Formulas.............................................................................................................................................373
Writing and debugging formulas..............................................................................................374
Formula return types................................................................................................................376
Examples of valid string tokens................................................................................................376
Using dates in formulas............................................................................................................377
Example using images to represent record status...................................................................377
Formula execution limits..........................................................................................................378
Group functions........................................................................................................................378
Typical mistakes in formulas....................................................................................................379
Triggers and workflows.......................................................................................................................381
Trigger overview.......................................................................................................................381
Workflow overview...................................................................................................................413
Automating business decisions with Corticon rules............................................................................427
Supported relationships for request mapping..........................................................................430
Supported relationships for response mapping........................................................................431

Contents
Supported data types and conversions....................................................................................433

Creating a Corticon Decision Service Trigger..........................................................................436
Overriding functions to provide custom behavior ....................................................................441
Example trigger mapping to related objects.............................................................................443
Example trigger mapping where response creates a record...................................................445
Reports, charts, and gauges...............................................................................................................447
Working with reports.................................................................................................................448
Working with charts..................................................................................................................471
Working with gauges................................................................................................................475
Multi-currency support........................................................................................................................477
Surveys and quizzes...........................................................................................................................480
Creating a survey.....................................................................................................................481
Enabling surveys on an existing object....................................................................................482
Adding questions to a survey ..................................................................................................484
Creating a question library.......................................................................................................486
Survey pages and links............................................................................................................486
Taking a survey........................................................................................................................487
Collecting survey answers.......................................................................................................488
Using surveys on portals..........................................................................................................488
Chapter 6: Customizing the user experience..........................................489

Pages, the page editor, and grid controls...........................................................................................490
Creating tabs and pages..........................................................................................................490
Managing object pages............................................................................................................492
Managing generic pages..........................................................................................................495
Editing pages...........................................................................................................................497
Using grid controls to manage multiple records.......................................................................511
Using buttons on pages...........................................................................................................515
Customizing the header and footer..........................................................................................518
Customizing application tabs and menus.................................................................................519
UI blueprints........................................................................................................................................525
Live Preview........................................................................................................................................531
Adaptive user interface.......................................................................................................................534
Automatic adaptive features for different devices....................................................................535
Cards and card containers.......................................................................................................538
Tailoring page components and views to devices....................................................................551
Customizing field labels...........................................................................................................553
Responsive user interface..................................................................................................................555
Vertical and horizontal responsive design................................................................................557
Responsive page title and toolbar............................................................................................559
Responsive dashboard pages..................................................................................................560
Working with views..............................................................................................................................561
Creating and editing views.......................................................................................................561
Adding columns........................................................................................................................562

Contents
Sorting and grouping................................................................................................................563

Calculating values for columns................................................................................................565
Filtering views..........................................................................................................................566
Editing a view on an application page......................................................................................572
Working with themes...........................................................................................................................578
Programmatic client-side customization.............................................................................................580
Custom CSS............................................................................................................................581
Custom themes........................................................................................................................584
HTML event handlers...............................................................................................................584
Rollbase AJAX APIs.................................................................................................................590
Rollbase portals..................................................................................................................................594
Creating a portal.......................................................................................................................596
Creating portal pages...............................................................................................................598
Creating a custom header and footer.......................................................................................607
Changing the main portal page................................................................................................609
Assigning pages to a portal......................................................................................................610
Portal security..........................................................................................................................610
Hosted files.........................................................................................................................................617
Managing hosted files..............................................................................................................617
Hosted file tokens.....................................................................................................................619
Using hosted file tokens...........................................................................................................619
Chapter 7: Supporting mobile users........................................................621

Using the Telerik Platform to create a mobile app..............................................................................622
Creating Progress Data Catalogs for use in the Telerik Platform.............................................623
Using the Views first approach.................................................................................................624
Creating a mobile app using Code and the Progress Data Service template..........................645
Mobile-Web enabled applications.......................................................................................................654
Chapter 8: Integrating with outside sources...........................................659

Creating Rollbase objects from OpenEdge Object Services..............................................................660
Limitations................................................................................................................................660
Supported data types...............................................................................................................661
Linking Rollbase external objects to OpenEdge data..............................................................662
Creating an application from OpenEdge data..........................................................................665
Using DataDirect Cloud to access external data................................................................................678
Calling Progress Corticon decision services from Rollbase................................................................681
Creating a Rollbase application from Microsoft Access......................................................................681
Uploading the MDB file............................................................................................................681
Creating objects from MDB tables...........................................................................................682
Mapping fields and creating records........................................................................................684
Reviewing results.....................................................................................................................688
Creating a Rollbase application from a Salesforce application...........................................................690

Contents
Migrating the application..........................................................................................................691

Using external tables as Rollbase objects..........................................................................................692
Using an external database and external objects for Private Cloud........................................692
Creating an external object from an external database table..................................................697
Importing data.....................................................................................................................................699
Compatible import data types..................................................................................................700
Importing for existing objects...................................................................................................701
Importing to create a new object..............................................................................................703
Importing related objects..........................................................................................................704
Deleting multiple records by importing a spreadsheet........................................................................705
Exporting from views and reports.......................................................................................................706
Integrating with Google applications...................................................................................................707
Enabling Google integration.....................................................................................................708
Incoming Gmail........................................................................................................................709
Outgoing Gmail........................................................................................................................711
Google spreadsheets...............................................................................................................711
Synchronizing with Google Calendar.......................................................................................711
Google Maps............................................................................................................................712
Using SOAP or REST to integrate with Rollbase................................................................................714
Limits on API calls....................................................................................................................715
Monitoring API calls.................................................................................................................715
Integrating apps using Cloud Data Objects........................................................................................716
Creating Progress Data Catalogs for external applications.....................................................717
Integrating with Microsoft Exchange Server.......................................................................................718
Chapter 9: Security and access control...................................................719

User authentication.............................................................................................................................720
Forgotten password.................................................................................................................721
Whitelist IP addresses..............................................................................................................721
Access control.....................................................................................................................................724
Role-based access control.......................................................................................................724
User-based access control.......................................................................................................740
Relationship-based permissions..............................................................................................742
Page versions..........................................................................................................................746
Location/department/function permissions...............................................................................748
User authentication and password management ...............................................................................759
Enabling an administrative user to log into a customer tenant...........................................................761
Enhanced hashing and encryption algorithms ...................................................................................762
Security for portals..............................................................................................................................763
Chapter 10: Publishing and distributing applications............................765

Using the Progress Rollbase Marketplace..........................................................................................766
Publishing an application to the Marketplace...........................................................................769

Contents
Enabling or disabling Marketplace in Rollbase Private Cloud..................................................771

Managing the Marketplace using the Marketplace application in Rollbase Private Cloud.......773
Distributing applications in XML format...............................................................................................779
Components included in an application XML file.....................................................................779
Use of original IDs....................................................................................................................781
Locking applications.................................................................................................................782
Attaching seed records............................................................................................................783
Testing and verifying application correctness...........................................................................783
Generating application XML.....................................................................................................784
Publishing to the Rollbase Application Directory......................................................................785
Providing a test drive................................................................................................................786
Administrative management of published applications............................................................786
Troubleshooting published applications..............................................................................................787
Chapter 11: Advanced setup and administration....................................791

Personal setup....................................................................................................................................791
My Settings page.....................................................................................................................792
Third Party Settings page.........................................................................................................793
My Localization Settings page.................................................................................................793
My Preferences page...............................................................................................................794
My Security Settings page.......................................................................................................796
Change Password page...........................................................................................................797
Recycle Bin page.....................................................................................................................797
Administration setup...........................................................................................................................798
Transfer owners.......................................................................................................................800
Using company-wide settings..................................................................................................800
Backup and restore..................................................................................................................804
Currency formats......................................................................................................................807
Batch jobs................................................................................................................................811
Billing and support settings......................................................................................................813
Global text search....................................................................................................................813
Monitoring setup.................................................................................................................................813
Support................................................................................................................................................814
Language support...............................................................................................................................815
Adding support for other languages in Private Cloud..............................................................817
Translating applications............................................................................................................818
Enabling Google Apps for Rollbase Private Cloud.............................................................................828
Chapter 12: Installing and administering Private Cloud........................831

Introduction.........................................................................................................................................831
Platforms supported for Private Cloud.....................................................................................833
Licensing..................................................................................................................................834
OpenEdge license restrictions.................................................................................................834

Contents
Private Cloud updates..............................................................................................................834

Included Rollbase applications.................................................................................................834
Third party software you can install..........................................................................................835
Installation...........................................................................................................................................836
Prerequisites............................................................................................................................837
Using the Rollbase installer......................................................................................................837
Postrequisites...........................................................................................................................841
Using your own instance of Tomcat ........................................................................................842
Setting up Rollbase manually...................................................................................................842
Configuring a supported database...........................................................................................845
Configuring PD4ML..................................................................................................................850
Starting components and logging In.........................................................................................851
Activating your license.............................................................................................................852
Troubleshooting........................................................................................................................853
Administration.....................................................................................................................................855
Overview..................................................................................................................................856
Monitoring system components...............................................................................................857
Monitoring system health.........................................................................................................859
Managing customer tenants.....................................................................................................859
Managing databases................................................................................................................868
Application Directory, Marketplace, and support portal............................................................873
Setting up ISV partners............................................................................................................874
Private Cloud security and access control..........................................................................................874
Supported methods of authenticating users.............................................................................874
Setting the authentication method............................................................................................874
Password authentication..........................................................................................................875
External authentication.............................................................................................................881
API authentication....................................................................................................................897
Security questions for authentication.......................................................................................898
Configuring Rollbase Private Cloud to use HTTPS..................................................................900
Multi-server environments...................................................................................................................901
Planning your multi-server architecture....................................................................................902
Configuring multiple instances of Rollbase components ........................................................911
Configuring high availability.....................................................................................................914
Configuration file reference.................................................................................................................917
components.xml...................................................................................................................917
databases.xml.....................................................................................................................922
events.xml............................................................................................................................923
fieldgroups.xml.................................................................................................................923
legacyobjects.xml.............................................................................................................923
listitems.xml.....................................................................................................................924
license.xml.........................................................................................................................924
securityLevel.xml.............................................................................................................924
servicelevel.xml...............................................................................................................925

Contents
shared.properties.............................................................................................................926
PAS command line reference.............................................................................................................940
The tcman command...............................................................................................................940
Manager actions.......................................................................................................................942
Server actions..........................................................................................................................953
General actions........................................................................................................................973
Chapter 13: Setup and administration for ISVs.......................................977

Getting started....................................................................................................................................978
System applications............................................................................................................................979
Creating a custom login page.............................................................................................................980
Creating a page for users to retrieve passwords................................................................................980
Customizing page title tags.................................................................................................................981
Using a third-party cloud service for storage......................................................................................982
Using Amazon S3....................................................................................................................982
Using Microsoft Azure..............................................................................................................984
Using the ISV Partner application.......................................................................................................985
Creating and managing customer tenants...............................................................................986
Pushing application updates to other tenants.....................................................................................986
Installing application updates..............................................................................................................987
Version history and rolling back..........................................................................................................988
Chapter 14: Reference...............................................................................989

Server-side API...................................................................................................................................989
API error messages.................................................................................................................990
Query API.................................................................................................................................990
Object Script API....................................................................................................................1007
User selection API..................................................................................................................1023
Miscellaneous methods..........................................................................................................1026
Date, time, and currency API.................................................................................................1032
PDF processing API...............................................................................................................1037
Hosted file API.......................................................................................................................1038
HTTP API...............................................................................................................................1039
XML processing API...............................................................................................................1042
JSON processing API............................................................................................................1044
Trigger to trigger API..............................................................................................................1045
Trigger environment API........................................................................................................1046
Debugging API.......................................................................................................................1051
Log API..................................................................................................................................1054
Email API...............................................................................................................................1056
User session data API............................................................................................................1059
Client-side AJAX API........................................................................................................................1064
Queries...................................................................................................................................1064

Contents
Field Manipulation..................................................................................................................1091
Data Formatting.....................................................................................................................1095
Grid Control Examples and API.............................................................................................1099
Miscellaneous........................................................................................................................1122
Display Functions...................................................................................................................1133
User session data..................................................................................................................1144
Client-side JavaScript.......................................................................................................................1150
Objects...................................................................................................................................1151
Functions................................................................................................................................1158
Properties...............................................................................................................................1161
Custom events.......................................................................................................................1169
Code Generator................................................................................................................................1171
Using the Code Generator.....................................................................................................1172
Metadata API and XML Reference...................................................................................................1173
Metadata XML reference........................................................................................................1173
SOAP Metadata Methods......................................................................................................1190
REST Metadata Methods.......................................................................................................1203
Rollbase REST Methods...................................................................................................................1216
appXML .................................................................................................................................1217
bulkCreate .............................................................................................................................1217
bulkCreateOrUpdate .............................................................................................................1218
bulkDelete .............................................................................................................................1220
bulkUpdate ............................................................................................................................1221
clearDataObjectCache...........................................................................................................1222
create ....................................................................................................................................1223
createArr................................................................................................................................1224
createCustomer .....................................................................................................................1226
create2 ..................................................................................................................................1227
createRecord..........................................................................................................................1228
delete ....................................................................................................................................1230
deleteArr ................................................................................................................................1230
deleteRecord..........................................................................................................................1231
getApplicationIds....................................................................................................................1232
getAuthentication...................................................................................................................1233
getBinaryData........................................................................................................................1234
getBuildStatus........................................................................................................................1235
getCodeById .........................................................................................................................1236
getCount ................................................................................................................................1237
getDataField ..........................................................................................................................1238
getDataObj ............................................................................................................................1239
getIdByCode .........................................................................................................................1241
getIdByOriginalId....................................................................................................................1242
getLDFIDs..............................................................................................................................1243
getPage .................................................................................................................................1244
getPermissionsByRole...........................................................................................................1246

Contents
getPermissionsByUser...........................................................................................................1247
getPicklist...............................................................................................................................1249
getRecord...............................................................................................................................1250
getRelationships ....................................................................................................................1251
getRoleById............................................................................................................................1253
getRoles.................................................................................................................................1254
getUpdated ............................................................................................................................1255
header ...................................................................................................................................1256
install .....................................................................................................................................1256
installByAppId .......................................................................................................................1257
licenseUpdate........................................................................................................................1258
login........................................................................................................................................1259
logout.....................................................................................................................................1260
resetPassword.......................................................................................................................1261
runAction................................................................................................................................1262
runTrigger ..............................................................................................................................1263
search ...................................................................................................................................1264
selectNumber ........................................................................................................................1265
selectQuery ...........................................................................................................................1266
selectValue ............................................................................................................................1268
setAuthentication....................................................................................................................1269
setBinaryData.........................................................................................................................1275
setDataField ..........................................................................................................................1276
setPermissionsByRole...........................................................................................................1277
setPermissionsByUser...........................................................................................................1278
update ...................................................................................................................................1279
updateArr...............................................................................................................................1281
updateCustomer ....................................................................................................................1282
updateRecord.........................................................................................................................1283
update2..................................................................................................................................1284
view .......................................................................................................................................1285
Rollbase SOAP Methods..................................................................................................................1285
DataObj Container Class.......................................................................................................1286
DataField Container Class.....................................................................................................1287
SearchFilter Class .................................................................................................................1287
bulkCreate() ..........................................................................................................................1289
bulkCreateUpdate() ...............................................................................................................1289
bulkUpdate() ..........................................................................................................................1290
clearDataObjectCache().........................................................................................................1291
create() ..................................................................................................................................1292
createArr() .............................................................................................................................1293
createArr2() ...........................................................................................................................1294
createArrNoAudit() ................................................................................................................1295
createCustomer() ..................................................................................................................1296
createRecord().......................................................................................................................1297

Contents
delete() ..................................................................................................................................1297
deleteArr() .............................................................................................................................1298
deleteArrNoAudit().................................................................................................................1299
deleteRecord().......................................................................................................................1299
deleteRecords()......................................................................................................................1300
detailedSearch().....................................................................................................................1301
getBinaryData() .....................................................................................................................1302
getCodebyId() .......................................................................................................................1303
getCount() .............................................................................................................................1303
getIdByCode() .......................................................................................................................1304
getDataField() .......................................................................................................................1305
getDataField2() .....................................................................................................................1306
getDataObj() ..........................................................................................................................1307
getExchangeRate() ...............................................................................................................1308
getPage() ..............................................................................................................................1308
getRelatedIDs()......................................................................................................................1310
getRelationships() .................................................................................................................1310
getRuntimeStatus() ...............................................................................................................1311
getUpdated() .........................................................................................................................1312
getRecord()............................................................................................................................1313
login().....................................................................................................................................1314
login2()...................................................................................................................................1314
logout() ..................................................................................................................................1315
resetPassword().....................................................................................................................1316
selectNumber() ......................................................................................................................1316
selectQuery() .........................................................................................................................1317
selectValue() ..........................................................................................................................1319
setBinaryData() .....................................................................................................................1320
setDataField() ........................................................................................................................1321
setDataField2() ......................................................................................................................1322
setExchangeRate() ...............................................................................................................1323
setRelationship() ...................................................................................................................1324
setRelatedIDs() .....................................................................................................................1325
textSearch() ...........................................................................................................................1326
update() .................................................................................................................................1326
updateArr() ............................................................................................................................1327
updateArrNoAudit()................................................................................................................1328
updateCustomer() .................................................................................................................1329
updateRecord.........................................................................................................................1330
Rollbase CSS Styles for the Classic UI............................................................................................1331
Table Styles............................................................................................................................1331
Table Cell Styles.....................................................................................................................1332
Table Row Styles....................................................................................................................1335
Text Styles..............................................................................................................................1337
Page Editor Styles..................................................................................................................1338

Contents
Link Styles..............................................................................................................................1338
Sidebar Styles........................................................................................................................1339
Field types.........................................................................................................................................1339
Text field.................................................................................................................................1339
Text Area Field.......................................................................................................................1340
Checkbox Field......................................................................................................................1340
Decimal field...........................................................................................................................1340
Currency field.........................................................................................................................1340
Base Currency field................................................................................................................1341
Date Field...............................................................................................................................1341
Date/Time field.......................................................................................................................1341
Time field................................................................................................................................1342
Email Field.............................................................................................................................1342
Phone Number field...............................................................................................................1342
Password Field.......................................................................................................................1342
Integer field............................................................................................................................1343
Percent Field..........................................................................................................................1343
Picklist Field...........................................................................................................................1343
Picklist Multiselect..................................................................................................................1345
Radio Button Field..................................................................................................................1345
Group Checkbox Field...........................................................................................................1345
URL Field...............................................................................................................................1346
Auto-Number Field.................................................................................................................1346
File Upload field.....................................................................................................................1346
Image Upload field.................................................................................................................1347
Shared Image field.................................................................................................................1347
Formula Field.........................................................................................................................1347
Expression Field.....................................................................................................................1349
Template Field........................................................................................................................1349
Document Template Field......................................................................................................1349
Email Template Field..............................................................................................................1350
Related Field..........................................................................................................................1350
Integration Link Field..............................................................................................................1350
Dependent Picklist Field.........................................................................................................1351
Version Number Field.............................................................................................................1351
Reference Field......................................................................................................................1351
Advanced field properties.......................................................................................................1352
System Field Types................................................................................................................1352
Portal Field Types..................................................................................................................1354
Chapter 15: Getting help .........................................................................1357
Chapter 16: Third-party acknowledgements.........................................1359

Contents
Rollbase Public Cloud Third-party acknowledgements.....................................................................1359

Rollbase Private Cloud Third-party acknowledgements...................................................................1370

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.

Chapter 1: Copyright

1
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.

Chapter 1: Introduction to Progress Rollbase
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.

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:
Click the thumbnail to view the typical Rollbase app development cycle.

Rollbase offers a flexible and mature environment, suitable for the most demanding of applications:
• Platform options
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 977
• 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
• Learn with hands-on exercises
• 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.
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 724 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 859 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 Password authentication details
on page 876 for more information.

Obtaining an account
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 898 for information about configuring security questions.
See Selecting and modifying your security questions on page 25 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 Personal setup on page 791 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.
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.

Basic Rollbase concepts
You are now logged in to the other tenant.
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 621 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.
• 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 266 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 525 for more information.

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.

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 538 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 32

• Setup and setup page components on page 40
• The Rollbase application on page 44
• Search on page 44
• Printing and PDF generation on page 50

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 on page 32

• The application tab and menu bar on page 35 (Traditional UI blueprint only)
• The application switcher on page 38 (Modern - Vertical Menus UI blueprint only)
• The Page Options menu on page 39 (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 247 for a list of application page types.
The Rollbase menu

Access the Rollbase menu by clicking the icon in the top left corner of any application page.

The screen below shows the Rollbase menu for an application that uses the Traditional UI blueprint.
The screen below shows the Rollbase menu, also known as the sidebar, for an application that uses the Modern
- Vertical Menus UI blueprint.

The Rollbase menu contains the following navigational controls:
• Rollbase Home — Opens the Rollbase application (administrators and users with permission to view the
Rollbase application only)

• Help Me — Opens the Rollbase documentation

• New Application — Launches the Create Application dialog (administrators only)
• 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.
• Recycle Bin — Opens the Rollbase 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 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.
• My Theme — Opens the Theme Preview mode, allowing a user to select a theme for all applications. See
Selecting a theme for a user on page 288 for details.
• Subscription Details — Opens the About Your Account page, which displays details about your user
account. One of the important pieces of information on the page is your Customer ID.
• 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.
For administrative users, the Rollbase menu also contains the following controls:
• Pacific Home — Opens the Progress Pacific home page

• Getting Started — Launches a page with information and links to help you get started developing applications
• Install Applications — Opens the Application Marketplace, where you can find and install ready-made
Rollbase applications
• Live Preview — Opens Live Preview, 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.
• Setup Home — Opens the Setup Home page, where administrators can navigate to administrative and
development pages. See Setup and setup page components on page 40 for more information.
• Manage Users — Opens the Users page in the Rollbase application. This page lists all users in the tenant
and allows you to view, create, edit, and delete user records.
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 on the application tab that allows the user to navigate to different
applications and to setup pages. Select the App Settings button next to an application to navigate to the
application's setup page:
Note: The application switcher on page 38 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. 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 on page 32 (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:
• 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 38 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 on page 32 (sidebar) for applications that
use the Modern - Vertical Menus UI blueprint.

See Application tabs and menus on page 255 for more information about tabs and menus.
The application switcher

For applications that use the Modern - Vertical Menus UI blueprint, the application switcher is at the upper right
corner of the page:
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.
See The application tab and menu bar on page 35 for information about the application switcher for applications
that use the Traditional UI blueprint.

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 50 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 page 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)

Administrative users have the additional option to navigate to the object definition for the displayed object type:
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 274 for information about setting the logo for an application. See Account settings on page
801 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:
The following is the Setup home page of hosted Rollbase:

All setup pages contain the following navigational components:
• The application switcher on page 42

• The left navigation pane on page 43
• Search on page 44
The application switcher

All setup pages contain the application switcher:
The application switcher allows you to navigate to application and setup pages in the following ways:
• Rollbase Home — Opens the Rollbase application.

• Setup Home — Opens the Setup home page.
• Current App Settings — Opens the application settings for the Rollbase application.
• Application name — Opens the main page for the selected application.
• Application setup link — Click the icon to the right of an application to open its setup page.

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:

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 260.
For information about attaching a Google account, see Integrating with Google applications on page 707.
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.

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 1352 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 725 for more information.

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

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 44 and select the object type from the drop-down menu.
• Select Search from the page menu:

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.

Metadata search
Metadata stores the definition of Rollbase applications and their components, including properties and attributes.
Metadata XML reference on page 1173 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 46.
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.

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:


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.

Learn with hands-on exercises
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.
Learn with hands-on exercises

The fastest way to learn how to use Rollbase is to get started with a simple app. The Quick Start tutorial walks
you through the the creation of an app that demonstrates use of the features described in the following table.
The links go directly to the relevant content, but to reproduce the app, start at the beginning of the tutorial.
Feature See how to: Tutorial Video
Quick Create wizard Create objects, fields, and

relationships

Feature See how to: Tutorial Video
User accounts Set up roles and user

account records
Record name template Automatically create a

value for the record name
field
Auto-number field Add a field for which

Rollbase generates a
numbered value
Simple formula Insert the current date into

a field
Formula with date Insert a future date based

calculation on the current date
Simple trigger Use a trigger to change a

field's value
Trigger and conversion Create a conversion map

map and a trigger that creates
a new record from values
in another
Views Create a view that

displays only records with
a particular value
Roles Grant permission by role
Themes Change the application

theme for all users
Header and footer Upload a graphic and

modify pages to use a
custom header and footer
Application tabs Change the labels and

order in which tabs appear
in the application
Pages Specify the controls and

fields to display
Help for end-users Enable field-level help

Sample applications
Sample applications
Another good way to become familiar with Rollbase is to install one or more ready-made starter applications
from the Marketplace or 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.
Hosted Rollbase Marketplace or Application Directory contains only applications approved by Rollbase.
Rollbase Private Cloud Marketplace or Application Directory is similar, but the administrator of the master
tenant decides which applications will be available in it. Administrators can install any application from the
Application Directory 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 or Application Directory 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 766.


2
What's new in this release
The topics in this section describe new features and changed behavior for Rollbase for the following releases:
• Release 4.5
• Release 4.4
• Upgrading Private Cloud to Version 4.X on page 235
• Release 4.3
• What's new in Rollbase 4.3 on page 112
• What's new in Rollbase 4.3.1 on page 109
• Release 4.2
• Release 4.1
• Release 4.0

Chapter 2: What's new in this release

• What's New in Rollbase 4.5.8
• What's new in Rollbase 4.5
• What's new in Rollbase4.4.4
• What's new in Rollbase 4.3.1
• Upgrading Private Cloud to Version 4.X
What's New in Rollbase 4.5.8

Set parser preferences
Rollbase now enables you to set parser preferences (Default, Aspose, and Built-in) for DOC, PDF, and DOCX
documents. You can make Aspose parser as the default option for DOC, PDF, and DOCX by modifying
IsAsposeDocParserEnabled, IsAsposePDFParserEnabled, and IsAsposeDocxParserEnabled
respectively. See Working with customer records for more information.

What's new in Rollbase 4.5
SAML/ADFS - Support for SHA-256 as a request signature method Algorithm

Rollbase now lets you select a signature method alogorithm (global and per tenant level) 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.
See Configuring SAML/ADFS authentication details for all tenants on page 895, Configuring SAML/ADFS
authentication details for a tenant on page 893, and setAuthentication on page 1269 for more information.

Release 4.5 contains the following improvements:
• 4.5 User interface-related changes

• 4.5 Security and authentication-related features on page 60
• 4.5 Private Cloud changes
• 4.5 API-related changes on page 61
4.5 User interface-related changes

The following describe new features and changes related to the user interface and end user experience:
• Access to REST endpoints without writing code on page 59

• Improved charts and gauges on page 59
• Ability to tailor generate document file names on page 60
• Ability to create conditional formula for custom buttons and control button's position on page 60
• UML Diagram enhancement on page 60
• Ability to disable inline editing on page 60
• Ability to disable exporting on page 60
• Ability to move storage on page 60
Access to REST endpoints without writing code

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.
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 387 for more information.
See REST Service trigger on page 397 for more information.
Improved charts and gauges

Rollbase now supports horizontal and vertical gauge styles. In addition, more properties are added to fusion
charts and gauges to modernize them.
See Creating charts on page 471 and Creating and configuring gauges on page 476 for more information.

Ability to tailor generate document file names

You can now dynamically genrate document file names for every document template or report that you create.
See Creating a new document template on page 370 and Working with reports on page 448 for more information.
Ability to create conditional formula for custom buttons and control button's position
You can now create conditional formula for custom buttons. This conditional formula is evaluated before adding
a button to the page.
Also, Rollbase now enables you to control how the buttons (custom buttons and workflow action buttons) are
positioned in relation to the overflow menu.
See Using buttons on pages on page 515 for more information.
UML Diagram enhancement

Rollbase generates a Entity-Relationship (ER) UML diagram that helps you visualize application objects and
relationships. 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.
See View Diagram on page 278 for more information.
Ability to disable inline editing

You can now 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.
See Inline editing on page 572 for more information.
Ability to disable exporting

Rollbase now enables you to hide individual export options by adding a JavaScript code to Application custom
header section (to apply changes to the entire application).
See Exporting from views and reports on page 706 for more information.
Ability to move storage

As a master tenant, you can now move a customer storage from one storage type to any other storage type
using the Storage Move option from the More Actions menu. This provides you with the additional flexibility
to move storage no4.5 user interface related changest just from local -cloud but also, from cloud-cloud, and
cloud-local.
See Working with customer records on page 862 for more information.
4.5 Security and authentication-related features

This release contains the following security-related features:
• Custom authentication for Private Cloud on page 60

• Password policy update notifications on page 61
Custom authentication for Private Cloud

Private Cloud customers can develop and deploy a custom authenticator as an alternative to authentication
methods provided by Rollbase.

The procedure requires a Java class that implements the com.rb.util.interfaces.IAuthenticator

interface, and a configuration that identifies the class in the shared.properties file.
See Custom authentication for Private Cloud on page 389 for more information.
Password policy update notifications

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.
For details on this feature, see User authentication and password management on page 759
4.5 API-related changes

This release contains the following API-related changes:
• Added optional parameters to Server Side API sendHTTPGet method

• Added optional parameters to Client Side AJAX API rbf_runTrigger method
• Added optional parameters to Server Side API rbv_api.runTrigger method
• Added optional parameters to REST API setAuthentication method
• Added Client Side AJAX API getViewPage method
• Added Client Side AJAX API getViewCount method
Added optional parameters to Server Side API sendHTTPGet method

>
Added optional parameters to Server Side API sendHTTPGet method to supply header data, and to override
the default encoding scheme of the response.
rbv_api.sendHTTPGet(url,headers,charset);
where:
• headers is a String of name-value pairs specifying the HTTP Headers to be sent in the request.
• charset specifies the preferred encoding scheme for the HTTP response. Default value is UTF-8.
Example:
var headers = {"Content-Type": "application/xml"};
rbv_api.sendHTTPGet("http://xyz.com?abc=def",headers,"ISO-8859-1");
See rbv_api.sendHttpGet() on page 1039 for more information.
Added optional parameters to Client Side AJAX API rbf_runTrigger method

>

Added optional parameters to Client Side API rbf_runTrigger method to supply date format, and to allow
actions such as recursion and rollbackOnException to run.
rbf_runTrigger(objName, id, triggerId, checkCondition, callback, useLegacyDateFormat,
options);
where:
• 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 is list of name-value pairs set in a variable in the form {name1 : value1 , name2 : value2}.
When runRecursions is set to true, configures trigger to run recursively, assuming recursive properties
are set on the trigger definition page. Default value is false.
Example:
<script>
var options = {runRecursions : true};
var callback = function callback(returnStatus) {console.log("Trigger Status:
"+returnStatus);};
var func = rbf_runTrigger("a", 1234, "abcxyz", false, callback, false, options);
</script>
See rbf_runTrigger() on page 1081 for more information.
Added optional parameter to Server Side API rbv_api.runTrigger method

>
Added optional parameter to Server Side API rbv_api,runTrigger method to enable recursion.
rbv_api.runTrigger(objName, objId, triggerOrigId, checkValidation, runRecursions)
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.
Example:
rbv_api.runTrigger("Query", {!id}, "TaC4hpbwSDmjSPOHavRqJA", false, true);
See rbv_api.runTrigger() on page 1020 for more information.
Added parameters to REST API setAuthentication method

>
Added parameters to REST API setAuthentication method to retrieve and/or set the password reset link
expiry time and the knowledge factor token.
• passwordActivationContextExpiry is the password activation link expiry time for password
authentication.
• useKnowledgeFactorToken must be set to true to use a knowledge factor token for password
authentication.
• samlAuthnContextComparison must be set with one of the four comparison values for SAML/ADFS
authentication.
See setAuthentication on page 1269 for more information.

Added Client Side AJAX API rbf_getViewPage method

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
rbf_getViewPage(viewId, callback, options);
where:
• viewId is the original ID of the view.
• callback is 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.
• 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 (o by default).
• objNames: The list of integration names of objects to be fetched as composites (* or all by default).
• fieldList: A comma-separated list of field names to fetch (use "*" for all fields - default value).
• 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.
• sorting: The sorting to be applied on the view.
• langCode: A valid two-letter ISO language code, for example, {"langCode":"es"}.
Example:
rbf_getViewPage("12345", my_callback, {
"useLegacyDateFormat": false,
"startRow": 0,
"rowsPerPage": 1000,
"composite": {
"level": 1,
"objNames": "order"
},
"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"
});
See rbf_getViewPage on page 1073 for more information.
Added Client Side AJAX API rbf_getViewCount method

This function fetches the number of records in a view, after applying filters, if any.
rbf_getViewCount(viewId, callback, options);
where:
• viewId is the original ID of the view.
• callback is a callback function that will receive the record count as first parameter.
• options An optional JSON object that sets the values of optional arguments.
Example:
rbf_getViewCount("12345", my_callback,
{
"filtering": {
"dateFilter": [{
"field": "DOB",
}],
"filters": [
{
"field": "amount",
"value": "1606",
"opCode": "GE"
},
{
"field": "price",
"value": "102",
"opCode": "EQ"
}
],
"joinType": "OR"
}
});
See rbf_getViewCount on page 1068 for more information.
4.5 Private Cloud changes

The following new features are available for Private Cloud users:
• Workflow is merged into Storage Component on page 66

• Multi-threaded Processing for Batch Jobs on page 66
• Multi-threaded Processing for Import Jobs on page 66

• Additional shared properties for Rollbase Private Cloud on page 66

• Time to expire a lock reduced on page 67
Workflow is merged into Storage Component

Rollbase platform architecture is updated to merge lightweight storage and workflow components into one -
storage component. To support this, you must remove the workflow component entries in component.xml
configuration file, before you restart your server post upgrade.
Multi-threaded Processing for Batch Jobs

Rollbase can now be configured to run multiple threads to process the batch jobs for different customers. This
provides a performance improvement from sequential processing.
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.
To enable this functionality in a Rollbase Private Cloud, set the following property in an installation that has
been upgraded to 4.5:
• In the config folder, edit components.xml.
• Set the STORAGE SERVER component property BatchJobsExecutorThreadCount to your preferred
value (1 to 5) for the thread count of the Executor Service that runs the batch jobs. The default value is 1.
This property was added to the topic Component specific properties on page 918
Multi-threaded Processing for Import Jobs

Rollbase can now be configured to enable the customers to set the thread count of the import job scheduler
that runs import jobs simultaneously.
To enable this functionality in a Rollbase Private Cloud, set the following property in an installation that has
been upgraded to 4.5:
• In the config folder, edit components.xml.
• Set the MASTER SERVER and PROD N SERVER component property ImportJobsExecutorThreadCount
to your preferred value (1to 5) for the thread count of the scheduler that runs the import jobs. The default
value is 1.
This property was added to the topic Component specific properties on page 918
Additional shared properties for Rollbase Private Cloud

The following are new shared properties available on Rollbase Private Cloud:
Property Description
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


What's new in Rollbase4.4.4
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.
UseAdvancedEncryption When set to true, enables an installed Unlimited JCE to generate a

private key and use the AES-256 Symmetric Encryption Algorithm.
Default value is false.
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.
These properties were added to the table shared.properties on page 926.
Time to expire a lock reduced

At LOW level, the default value of Minutes to wait before expiring record lock is documented to reflect its
actual behavior, reduced from 240 (4 hours) to 120 (2 hours.)
See Built-in security levels on page 876 for more information.
What's new in Rollbase4.4.4

Release 4.4.4 contains the following improvement:
• 4.4.4 Private Cloud changes on page 67
4.4.4 Private Cloud changes

The following new feature is available for Private Cloud users:
Upgraded 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.
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.
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 shared property - 'EncryptionType'.
To make use of AES-256 on a Rollbase Private Cloud:
1. Set value of shared property ‘EncryptionType’ from 0 to 1. This is a one-time setting.
Once set to 1, reverting to 0 is not recommended. If no value is specified,
‘EncryptionType’ uses its default value, 0. No additional changes are required if you
want to continue using AES-128.
2. Install Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files 8 to
enable the 256-bit Key Size used by AES-256. For download and usage instructions, see
http://www.oracle.com/technetwork/java/javase/downloads/jce8-download-2133166.html.
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.
See Enhanced hashing and encryption algorithms on page 762 for more information.

Release 4.4 contains the following enhancements and changes:
• An Integration with Progress Corticon that allows you to take advantage of a sophisticated decision service
• User interface-related changes
• Smart image uploading and rendering on page 70
• Support for simplifying import procedure on page 72
• Ability to position notification messages on page 74
• Trigger screen improvements on page 77
• Text change for new record button on record List pages on page 81
• New and improved editing capabilities

• Card Editor tools for adding custom scripts and CSS styles on page 83
• Improved table tools in rich text editor for Text Area fields on page 91
• Ability to select devices on which to display page tabs on page 92
• Ability to hide or show Export button on record List pages on page 93
• Ability to hide or show empty fields on View pages on page 94
• Ability to hide or show field labels on Edit pages on page 95

• New CSS class to size text areas on page 95
• Security and authentication-related features

• New user-level security settings on page 97
• Change to authentication fallback behavior on page 99
• Change to conditional field-level permissions when creating records on page 100
• Private Cloud features

• Support for single user multi-tenant in Rollbase Private Cloud on page 101
• Java 7 and Tomcat 7 no longer supported on page 101
• Ability to store password history on page 101
• API-related changes
• Multilingual support for client-side APIs on page 102
• New client-side function rbf_addOnLoadMethod() on page 103
• New client-side API support for accessing the page toolbar on page 104
• Improved formula debugging

• Miscellaneous
• Alternative way to open Recycle Bin on page 106
• Ability to populate existing records with default value of new field on page 107
• Cannot create or delete a Settings record on page 108
• Support for enabling native date/time/date-time controls restricted to mobile devices on page 109
• Updated Kendo UI library on page 109
4.4 Integration with Progress Corticon rules decision service

Progress Corticon is a Business Rules Management System with a patented rules engine that enables you to
automate sophisticated decision-making processes without coding them. The integration between Rollbase
and Corticon make it possible to rapidly develop adaptive applications to meet business needs.
The integration allows you to configure a connection to a Corticon server. A new trigger type, Corticon Decision
Service, allows you to send information from a Rollbase app to the Corticon Decision Service. The Decision
Service can then process the information and return a response. For example, an app could use a decision
service to generate a quote for life insurance based on a person's age, gender, health history, and other factors.
The trigger configuration includes a mapping tool to map fields from a Rollbase object to Corticon entity attributes
to create the request. You map fields from Corticon entity attributes and messages to fields in a Rollbase object
to create the response. The response can update fields in a record or create new records.

Requirements to use the integration include:
• Access to a Corticon Decision Service compiled and deployed using Corticon server version 5.6 or later.
• An understanding of the Decision Service functionality, the data it requires as input, and expected results.
See Automating business decisions with Corticon rules on page 427 for details and examples.
4.4 User interface-related changes

The following describe new features and changes related to the user interface and end user experience:
• Smart image uploading and rendering on page 70

• Support for simplifying import procedure on page 72
• Ability to position notification messages on page 74
• Trigger screen improvements on page 77
• Text change for new record button on record List pages on page 81
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.

Click the thumbnail to see the location of these two settings on the Field Properties screen.

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.

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:

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:


Selecting the option Bottom Corner positions notifications for that application as shown below.

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:


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:
4.4 New and 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 83
• Improved table tools in rich text editor for Text Area fields on page 91

• Ability to select devices on which to display page tabs on page 92

• Ability to hide or show Export button on record List pages on page 93
• Ability to hide or show empty fields on View pages on page 94
• Ability to hide or show field labels on Edit pages on page 95
• New CSS class to size text areas on page 95

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.


• 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;

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

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


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.

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 506 for more information about page tabs.
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:

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.

Ability to hide or show field labels on Edit pages

Administrators can now hide or show specific field labels on Edit pages from the page editor by selecting or
deselecting Hide Label in the field's Properties menu. Previously, hiding field labels on Edit pages required
writing code. See removeFieldLabel() on page 1161 for information about hiding field labels programatically.
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:

4.4 Security and authentication-related features

Release 4.4 contains the following security-related features:
• New user-level security settings on page 97

• Change to authentication fallback behavior on page 99
• Change to conditional field-level permissions when creating records on page 100

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
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:
• 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.
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.
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 737 for more information and example patterns for conditionalizing
formulas..
4.4 Private Cloud changes

The following new features are available for Private Cloud users:
• Support for single user multi-tenant in Rollbase Private Cloud on page 101
• Java 7 and Tomcat 7 no longer supported on page 101
• Ability to store password history on page 101
• Updated third party JAR files on page 101

Support for single user multi-tenant in Rollbase Private Cloud

In hosted Rollbase, the same email address can be associated with accounts in multiple tenants. Now, Private
Cloud instances support allowing a single user to access multiple tenants if global authentication is enabled
(SAML/ADFS or custom authentication). To enable support for this new feature, in the shared.properties
file, set IsSingleUserMultiTenantEnabled to true.
When enabled, the option to switch tenants is available from the profile menu for users who have accounts on
multiple tenants:
Java 7 and Tomcat 7 no longer supported

Starting with this release, Java 7 and Tomcat 7 are no longer supported. Please upgrade to Java 8 and Tomcat
8.
Note:
With Tomcat 8, 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"/>
Ability to store password history

Private Cloud administrators who use password authentication can now configure Rollbase to store up to ten
previous passwords for each user. When changing their passwords, users will not be allowed to use any of
the stored passwords.
Updated third party JAR files

Release 4.4 contains updated third party JAR files. You should remove the old JAR files when upgrading. See
Upgrading Private Cloud to Version 4.X on page 235 for the list of JARs to remove.

4.4 API-related changes

This release contains the following API-related changes:
• Multilingual support for client-side APIs on page 102

• New client-side function rbf_addOnLoadMethod() on page 103
• New client-side API support for accessing the page toolbar on page 104
Multilingual support for client-side APIs

Several client-side AJAX APIs now support fields that have values in multiple languages. You can now pass
a JSON object to specify the language for a field. All changes to the APIs are backward compatible.
The following APIs now support multilingual fields:
• rbf_getFieldValue(fieldName, options) — Use the options parameter to specify the language
in which to return the value.
See rbf_getFieldValue() on page 1091 for details.
• rbf_setFieldValue(fieldName, value, options) — Sets the value of the specified field. For
fields that can contain values in multiple languages, use the options parameter to specify the language
in which to set the value.
See rbf_setFieldValue() on page 1093 for details.
• rbf_setFieldDisabled(fieldName,isDisabled,options) — Disables or enables an input field

on the current page. For fields that allow values in multiple languages, use the options parameter to
specify the language for which to disable/enable the input field.
See rbf_setFieldDisabled() on page 1094 for details.
• rbf_getFields(objName, id, fields, callback, useLegacyDateFormat, options) —

Retrieves the values of specified fields for a selected Rollbase record. For fields that can contain values in
multiple languages, use the options parameter to specify the language in which to return the values.
See rbf_getFields() on page 1069 for details.
• rbf_createRecord(objName, fieldMap, useIds, callback, useLegacyDateFormat) —

Creates a new record without changing the UI presentation. For fields that allow values in multiple languages,
you can specify values in multiple languages using the fieldMap parameter.
See rbf_createRecord() on page 1065 for details.
• rbf_updateRecord(objName, id, fieldMap, useIds, callback, useLegacyDateFormat)

— Modifies record values of a RollbaseRollbase object without changing the UI presentation. For fields that
allow values in multiple languages, you can specify values in multiple languages using the fieldMap
parameter.
See rbf_updateRecord() on page 1090 for details.
• rbf_setField(objName, id, fieldName, fieldValue, useIds, callback,

useLegacyDateFormat) — Sets the value of specified field for a selected RollbaseRollbase record and
modifies the actual record value without changing the UI presentation. For fields that allow values in multiple
languages, you can set values in multiple languages using the fieldValue parameter.
See rbf_setField() on page 1088 for details.

• rbf_getPicklist(objName, fieldName, mainValueId, callback, options) — Returns

items available for selected picklist field (including radio buttons and groups of check box fields) as a JSON
array. For fields that allow values in multiple languages, use the options parameter to specify the language
in which to return the items.
See rbf_getPicklist() on page 1127 for details.
• rbf_getPage(viewId, startRow, rowsPerPage, composite, objNames, fieldList,

callback, onlyViewFields, useLegacyDateFormat, options) — Fetches a set of records in
a view, including (optionally) dependent records, using an asynchronous AJAX mechanism. For pages with
fields that allow values in multiple languages, use the options parameter to specify the language in which
to return those field values.
See rbf_getPage() on page 1070 for details.
• rbf_getPage2(viewId, startRow, rowsPerPage, composite, objNames, fieldList,

filterName, filterValue, callback, onlyViewFields, useLegacyDateFormat, options)
— Fetches a set of records in a view, including (optionally) dependent records, using an asynchronous
AJAX mechanism. Unlike rbf_getPage() on page 1070, you can filter the results. For pages with fields that
allow values in multiple languages, use the options parameter to specify the language in which to return
the field values.
See rbf_getPage2() on page 1072 for details.
• rbf_getRelatedFields2(relName, objName, id, fieldName, callback,

useLegacyDateFormat, options) — For external objects (such as those mapped to external tables,
to OpenEdge Service objects, or through a D2C connection), retrieves the values of the selected fields for
records related to a selected Rollbase record. For fields that allow values in multiple languages, use the
options parameter to specify the language in which to return field values.
See rbf_getRelatedFields2() on page 1079 for details.
• rbf_selectQuery(query, maxRows, callback, useLegacyDateFormat, options) — runs

a SQL SELECT query on the server and returns results as a 2D array to the callback function. For fields
that allow values in multiple languages, use the options parameter to specify the language in which to
return the values.
See rbf_selectQuery() on page 1084 for details.
• rbf_selectQuery2(query, maxRows, callback, useLegacyDateFormat, options) — runs

a SQL SELECT query on the server and returns results as a 2D array to the callback function. For fields
that allow values in multiple languages, use the options parameter to specify the language in which to
return the values.
See rbf_selectQuery2() on page 1085 for details.
• rbf_selectValue(query, callback, useLegacyDateFormat, options) — Runs a SQL SELECT

query on the server and returns a single value to the callback function. For fields that allow values in multiple
languages, use the options parameter to specify the language in which to return the value.
See rbf_selectValue() on page 1087 for details.
New client-side function rbf_addOnLoadMethod()

The new client-side function rbf_addOnLoadMethod(callback) attaches 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.
See rbf_addOnLoadMethod() on page 1123 for more information about this function. See HTML event handlers
on page 584 and Managing object pages on page 492 for more information about onload event handlers.

New client-side API support for accessing the page toolbar

The PageContext object now includes the function getPageToolbar(). This returns a PageToolbar
object that represents the page toolbar on an application page. The PageToolbar interface includes the
following functions:
• getItemByName()
• getItemsByClassName()
• getKendoConfig()
• getNode()
• showOrHideItem()
See PageToolbar on page 1158 for details.
4.4 Improved Formula debugging

This release includes the following:
• Improved formula debugging on page 104

• New debugging variable for trigger formulas on page 105
Improved formula debugging

In this release, 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.

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.

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);
}
}
4.4 Miscellaneous
This topic describes the following new features and changes:
• Alternative way to open Recycle Bin on page 106

• Cannot create or delete a Settings record on page 108
• Ability to populate existing records with default value of new field on page 107
• Support for enabling native date/time/date-time controls restricted to mobile devices on page 109
• Updated Kendo UI library on page 109
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:

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.
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:

What's new in Rollbase 4.3.1
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)

Release 4.3.1 contains the following improvements:
• Rollbase 4.3 features available on hosted Rollbase

• Changes to high availability configuration in Rollbase Private Cloud
• New parameter in runTrigger REST method
• Translations for Hebrew and Greek
Rollbase 4.3 features available on hosted Rollbase

All new features from Rollbase 4.3, except for those features specifically for Rollbase Private Cloud, are now
available on hosted Rollbase. See What's new in Rollbase 4.3 on page 112 for more information.
Changes to high availability configuration in Rollbase Private Cloud

Rollbase version 4.3 introduced high availability for Private Cloud.
Version 4.3.1 includes changes to the configuration. The original configuration included several shared properties.
All except one of those shared properties are now set in a new configuration file, hazelcast.xml, which is
included in the config directory (for example, C:\Progress\Rollbase\Pas_Instance\rollbase\config).

The following shows the content of hazelcast.xml:
<hazelcast xsi:schemaLocation="https://hazelcast.com/schema/config
hazelcast-config-3.7.xsd"
xmlns="http://www.hazelcast.com/schema/config"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<network>
<port auto-increment="false">5701</port>
<reuse-address>true</reuse-address>
<join>
<multicast enabled="false"></multicast>
<tcp-ip enabled="true">
<members></members>
</tcp-ip>
<aws enabled="false"></aws>
</join>
</network>
<properties>
<property name="hazelcast.heartbeat.interval.seconds">5</property>
<property name="hazelcast.max.no.heartbeat.seconds">30</property>
<property name="hazelcast.master.confirmation.interval.seconds">30</property>
<property name="hazelcast.max.no.master.confirmation.seconds">120</property>
<property name="hazelcast.socket.server.bind.any">false</property>
</properties>
<listeners>
<listener>com.rb.util.cluster.hazelcast.ClusterStateListener</listener>
<listener>com.rb.util.cluster.hazelcast.NodeLifecycleListener</listener>
</listeners>
</hazelcast>
This file includes configuration information as described below:

• port element — The port number. Defaults to 5701. Can be any value from 5701 through 5710. Replaces
the shared property HAClusterPort.
• members element — A comma-separated list of the IP addresses or hostnames of all members of the
cluster. Replaces the shared property HAClusterMembers.
• property element with name="hazelcast.heartbeat.interval.seconds" — The time interval,
in seconds, to send a heartbeat in a cluster. Defaults to 5. Replaces the shared property
HAHearbeatInterval.
• property element with name="hazelcast.max.no.heartbeat.seconds" — The maximum time, in
seconds, after which a non-responsive node is considered to be down. Defaults to 30. Replaces the shared
property HAMaxNoHeartbeat.
• property element with name="hazelcast.master.confirmation.interval.seconds" — The
time interval, in seconds, for confirmation from the master node. Defaults to 30. Replaces the shared property
HAMasterConfirmationInterval.
• property element with name="hazelcast.max.no.master.confirmation.seconds" — The
maximum time, in seconds, after which a non-responsive master node is considered to be down. Defaults
to 120. Replaces the shared property HAMaxNoMasterConfirmation.
• property element with name="hazelcast.socket.server.bind.any" — Helps to control socket
bind behavior. Do not change the value of this element.
• listener elements — Helps to control heartbeat behavior. Do not change the value of these elements.
The shared property IsHACluster still needs to be set to true to enable high availability. It defaults to false.
Configuration for environment variables and in the components.xml file remain the same.
See Configuring high availability on page 914 for the updated configuration instructions. See High availability
for the original configuration instructions.

New parameter in runTrigger REST method

The runTrigger REST method has a new parameter, runRecursions. When true, it configures the trigger
to run recursively, if recursive properties on the trigger definition page are set. Defaults to false if not set.
See Trigger overview on page 381 for more information about triggers.
Translations for Hebrew and Greek

Rollbase 4.3.1 includes translations for Hebrew and Greek. These translations are for text on application pages
that use the New UI. See Language support on page 815 for more information about supported languages and
translating applications.


• High availability
• Enhanced support for right to left languages and multilingual user interfaces
• Support for additional languages
• RTL support in templates and reports
• Namespaces in language resource files for Rollbase Private Cloud
• Revised grid control for New UI
• Improvements to Modern - Vertical Menus UI blueprint
• Support for horizontal card container
• Enhanced card editor
• Rebranding
• Image carousels enabled by default
• New UI performance improvements
• Updated UI libraries
• Support for ADFS authentication in Rollbase Private Cloud
• Enhanced Microsoft Access import
• Support for new currency formats
• New option for Send Email workflow action supports one-click email
• Ability to set and get login permission for the Customer object in Rollbase Private Cloud using REST APIs
• PDML4 PDF converter now bundled with Rollbase Private Cloud
• The System tab of the System Console in Rollbase Private Cloud contains additional information
• New preference to turn off welcome emails
• Additional information about the latest backup file and backup history included on Backup page
• Import jobs now run on Production server
• New behavior for removeAllSessionData APIs
• New client-side API rbf_getPageTabIndexByName(name)
• New shared property EmailEncodings
• Element CustWeight from components.xml is now a shared property
• Single click login deprecated
• Rollbase Mobile App Builder deprecated

High availability
Rollbase Private Cloud 4.3 includes the first phase of support for 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.
Rollbase supports high availability with the ability to configure active and standby Rollbase components in a
cluster of machines. Only active components handle requests.
Rollbase monitors each machine on which the components are running. Each machine sends a heartbeat as
configured by properties in the shared.properties file. If the machine running active components goes
down, the components on the standby machine are promoted to be the active components. If any machine in
the cluster goes down, Rollbase sends an email to the administrator. When the machine starts up again, its
components will be the standby components.
The diagram below shows the recommended architecture for high availability in Rollbase:
In the diagram, each node is a host. This configuration requires a minimum of six nodes to run Rollbase
components, plus a minimum of two Apache nodes, Amazon Cloud Services with ELB, and whatever is required
to run a highly available database:
• Node1A and Node1B — Run the Master server, Router server, REST server, SOAP server, and Workflow
server
• Node2A and Node2B — Run the Production server. Note that if you have multiple Production servers, each
must run on a different machine.
• Node3A and Node3B — Run the Storage server and the Search server
• Apache 1 and Apache 2 — A load-balanced high availability Apache cluster. This is required for high
availability in Rollbase 4.3. See An Active/Passive Apache Web Server in a Red Hat High Availability Cluster
for more information.
• AWS — Amazon Web Services with Elastic Load Balancing. This is required for high availability in Rollbase
4.3.
For the database Rollbase uses, refer to your database vendor for their high availability features.
Note: High availability configurations are only supported in this release for Rollbase running on Tomcat. See
Using your own instance of Tomcat on page 842 for more information.

To configure high availability:

• Set the following properties in the shared.properties file for the Rollbase installation on each node
running a Master server. Progress recommends leaving the values for HAHearbeatInterval,
HAMaxNoHeartbeat, HAMaxNoHeartbeat, and HAMasterConfirmationInterval at their defaults.
• IsHACluster — Set to true to enable high availability.
• HAClusterMembers — Set to a comma-separated list of the IP addresses or hostnames of all members
of the cluster.
• HAClusterPort — Defaults to 5701. You can set it to a value between 5701 and 5710.
• HAHearbeatInterval — The time interval, in seconds, to send a heartbeat in a cluster. Defaults to
5.
• HAMaxNoHeartbeat — The maximum time, in seconds, after which a non-responsive node is considered
to be down. Defaults to 30.
• HAMasterConfirmationInterval — The time interval, in seconds, for confirmation from the master
node. Defaults to 30.
• HAMaxNoMasterConfirmation — The maximum time, in seconds, after which a non-responsive
master node is considered to be down. Defaults to 120.
• On each node running Rollbase components, set the environment variable RB_NODE_NAME to a value
representing that node in the cluster. Each value must be unique in the cluster. If you are using a Tomcat
deployment, it is best to set environment variables using setenv.bat/sh in the tomcat/bin directory.
You will use the value of this environment variable in the components.xml file.
• Edit the components.xml file to include the following:
• Add a node attribute to each Component element that refers to the node on which it is deployed. The
value is the same as the value of the environment variable RB_NODE_NAME. For example, if
RB_NODE_NAME is set to Node1A, the corresponding Component element would look like the following:
<Component name="MASTER" type="MASTER" node="Node1A">

<DisplayName>Master Server</DisplayName>
<InternalRoot>http://mymachine.mycompany.com:8080/master/</InternalRoot>
<ExternalRoot>http://mymachine.mycompany.com/master/</ExternalRoot>
<Props>
<ResourcesCheck>2</ResourcesCheck>
<ExpirationDays>30</ExpirationDays>
</Props>
</Component>
• Add a list of Node elements representing each node in the cluster with a name attribute specifying its
node name (the value of the environment variable RB_NODE_NAME) and a role attribute specifying its
role. The value of the role attribute is arbitrary but must be the same for the two nodes that will act as
an active/standby pair – the role attribute represents the node's group in the cluster. For example, the
entries for the nodes from the above diagram would look like the following:
<Node name="Node1A" role="MASTER AND OTHERS"></Node>
<Node name="Node1B" role="MASTER AND OTHERS"></Node>
<Node name="Node2A" role="PRODUCTION"></Node>
<Node name="Node2B" role="PRODUCTION"></Node>
<Node name="Node3A" role="STORAGE AND SEARCH"></Node>
<Node name="Node3B" role="STORAGE AND SEARCH"></Node>

Enhanced support for right to left languages and multilingual user interfaces
Rollbase's multidirectional and multilingual features provide a no-code solution for building one application that
works well in multiple languages simultaneously, including languages that are written and read from right to
left (RTL) languages.
Note: RTL support is only available in the New UI.
Rollbase version 4.2 included experimental support RTL text direction. Rollbase version 4.3 enhances this
feature with official support for RTL rendering. Rollbase handles RTL rendering automatically based on the
user's language. For example, if the user's language is Arabic, Hebrew, or Farsi, user interface components
and text are rendered from right to left.
Details of Rollbase's multilingual support include:
• When using the New UI, Rollbase automatically renders application pages in the expected direction based
on the user's language. This includes page components as well as text. For example, record list columns
appear in order from right to left for users with a RTL language.
• Some icons on application pages are reversed when the user's language is RTL, for example, the pencil
icon is reversed. Arrows for next, previous, and back to list are also reversed.
• Rollbase automatically renders cards in the expected direction based on the user's language. You can
override the direction at the field level using the arrow button on the toolbar. See Creating and editing cards
• If a field contains text in multiple languages, Rollbase automatically renders the text of each language in
the correct direction. This is useful for applications such as travel or book review sites where users might
enter their reviews in multiple languages in the same text area.
• There are a few places where LTR text is required, such as in the JavaScript and HTML editors.
• The page editor now includes multilingual features:
• You can enter text for all enabled languages for section titles and page tab titles.
• You can create multilingual versions of the same HTML component. See Translating application
component names and labels on page 821 for details.
• Rollbase renders charts LTR, but chart labels can be provided in RTL languages.
• The Rollbase calendar is localized for RTL languages. For example, in Arabic, Saturday is first day of week
and is the rightmost day.
• The application setting Right to Left Text Direction, when selected, forces RTL text rendering for all
application pages, regardless of the user's language.
• Templates and most reports render text as LTR regardless of the user's language. However, you can make
some minor changes to override this default. See RTL support in templates and reports for details.
• Email encoding needs to be set to UTF-8 for RTL languages. This is the default for new customers only;
existing customers will have to change that setting on the My Settings page.
• The Classic UI does not support RTL rendering. This includes setup pages, portal pages, and the page
editor.
• . Setup pages are translated in most languages, but because they do not support RTL, they are not translated
to Arabic. See Language support on page 815 for details.
For more information about language support, RTL languages, and translating applications, see Language
support on page 815

Support for additional languages

Rollbase 4.3 includes support for Arabic, including translations for text on application pages:
When a user logs in with the language set to Arabic or Hebrew, the user interface automatically renders as
right-to-left.
Rollbase 4.3 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:
• Hebrew — Translations will be available soon.
• Turkish
• Greek
• Italian
Please contact Progress if you require translations for any of these languages.
On Rollbase Private Cloud, the Marketplace application now supports all of the above languages for published
applications. From the Marketplace application, select Published Applications, edit an application, and select
one or more languages from the Supported Languages drop-down menu. New Private Cloud instances will
already include the new language support. For existing Private Cloud instances, you should update the
Marketplace application from the file Rollbase_Home\pas\rollbase\apps\app4_mkp.xml. See
Installing and updating applications from XML on page 293 for more information about updating applications
from XML.
See Language support on page 815 for more information.
RTL support in templates and reports

Rollbase renders text in document templates, mail templates, and 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 template and report 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 page on page 792.
• When creating a mail template, select HTML as the format. See Email templates on page 365 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.
Reports
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 stylings for custom reports in two general ways:
• 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 Creating
custom reports on page 455 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 815.
Namespaces in language resource files for Rollbase Private Cloud

For Rollbase Private Cloud, you can use language resource files to add support for languages that are not
supported by Rollbase. Many property names now 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, 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 provide about 1000 translations instead of providing over 5000 translations to translate everything.
Note: If you have existing language resource files, please contact Progress. There is a utility available to
upgrade them to use namespaces.
See Adding support for other languages in Private Cloud on page 817 for more information.

Revised grid control for New UI

Rollbase provides the option to display related records on New, Edit, and Status pages. This release introduces
a revised grid control implementation.
The revised grid control is disabled by default in Rollbase 4.3. An administrator can enable it for the tenant on
the Preferences screen:

The revised grid control:

• Scales better than the old implementation. 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 1168 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.

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
• 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 1151 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
• 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'); }
);
Improvements to Modern - Vertical Menus UI blueprint

The Modern - Vertical Menus UI blueprint was experimental in Rollbase 4.2. In Rollbase 4.3, this blueprint is
now fully supported and includes the following improvements:

• 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..
Previously, users had to click an arrow to navigate to those tabs.
• On mobile devices, page tab names are now rendered in uppercase characters on View pages.
• On mobile devices, you can now 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.
• A new application setting, Use Native Calendar and Time Control, renders date and time controls as
native widgets on mobile devices:
When selected, if a user edits a date/time field, the native control appears to select it. For example, the
following screen shows the native date control on an iPad:
• The help menu now includes more documentation and support-related links:

• The user profile menu now includes the user name and Switch Tenant menu items:
Support for horizontal card container

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.

The following screen shows records displayed in a horizontal card container on a tablet:
Enhanced card editor

The card editor is enhanced in Rollbase 4.3. It now includes the following features:
• You can resize columns in the editor pane.
• You can drag and drop labels and values from the sidebar.
• The 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. This replaces HTML View in the previous release,
which opened the HTML in a separate window.
• Insert Link
• Insert Image
• Insert Video
• Upload File
• Insert table
• RTL and LTR 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.
The following screen shows the new card editor toolbar:

A new card tool, 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. The screen below shows the Add Text
Limit dialog:
A new card tool, 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. The screen below shows the Add Card Dimension dialog:

Rebranding
Progress logos have been updated on various screens in version 4.3 to reflect the new branding. The following
screen shows an application page with the new logo:
Image carousels enabled by default

Image carousels are now enabled by default. To disable image carousels for an application, set the property
rb.newui.options.useCarouselWhenMultipleImgFieldsInObject to false in a custom header
script or a custom sidebar script.
For more information about image carousels, see Image Upload field on page 1347.
New UI performance improvements

The New UI has the following performance improvements in Rollbase 4.3:
• I18N resources — The list of I18N (internationalization) resources cached on the client side has been
reduced by more than half. On mobile devices, the list has been reduced by 80% (from about 5000 resources
to about 1000).
• Recent items — Prior to version 4.3, the list of recent items that appears in the Rollbase menu were sent
as part of the initial page load server call. This has been changed to fetch the list of items separately after
the main page components load and reduces the JSON payload that is sent as part of the main page load
call. It also improves the performance of page render times.
• View pages with multiple list views — Rendering times for New UI View pages with multiple list views have
been fine tuned.
Updated UI libraries
The following libraries have been updated for version 4.3:
Library name From version To version

Font Awesome V4.5.0 V4.6.3
Kendo UI Professional 2016-1-226 2016-2-607
Bootstrap v3.3.6 Not changed
Bootstrap RTL V3.3.6 Not changed
JQuery V1.9.1 V1.12.3

Support for ADFS authentication in Rollbase Private Cloud

As resources move to the cloud , managing usernames and passwords of various resources becomes
increasingly difficult. To solve this issue, single sign-on technologies have emerged. Single sign on technologies
allow users to authenticate at a single location and access a range of services without re-authenticating. SAML
2.0 has become the dominant standard for cross-domain web single sign-on in the enterprise space. Active
Directory Federation Services (ADFS), a software component developed by Microsoft, can run on Windows
Server operating systems to provide users with single sign-on access to systems and applications located
across organizational boundaries. ADFS integrates with Active Directory Domain Services, using it as an identity
provider. ADFS can interact with other SAML 2.0-compliant federation services as federation partners. So any
business organization can leverage its Active Directory Domain Services and provide users a seamless single
sign-on experience from a Microsoft environment to rollbase.com (SAML 2.0 compliant federation service)
using ADFS.
Rollbase Private Cloud 4.3 supports authentication by ADFS. ADFS authentication is similar to SAML
authentication, except the IDP (Identity Provider ) in the authentication scheme is ADFS. The authentication
mechanism conforms to the SAML 2.0 specification. See SAML/ADFS authentication details for more information..
Enhanced Microsoft Access import

Importing a new application from Microsoft Access is simplified in this release. Rollbase now performs many
tasks automatically that you previously had to perform manually.
Enhancements to Microsoft Access import in this release include:
• Rollbase now reads the MS Access metadata and automatically generates primary keys and unique keys.
You are no longer required to select keys manually.
• Rollbase now supports composite unique keys and creates a Unique Fields Combination trigger for each.
• Rollbase now supports and automatically generates composite primary keys.
• Rollbase now reads all foreign keys in Access metadata and imports them as relationships. You are no
longer required to set up relationships manually.
• Rollbase now supports composite foreign keys and creates a single relationship for all participating columns.
For example, the key FOREIGN KEY sub_account (ref_num, ref_type) REFERENCES accounts (acc_num,
acc_type)) creates a single relationship between account and sub_account.
• Rollbase now preserves the values from database rows when mapping AutoNumber fields to Auto-Number
fields.
• You can now map any column with a string data type as the Record Name field for the object on the Create
Objects screen. Previously, you mapped a column to the Record Name field after the object definitions
had been created.
• You can now map Access Hyperlink fields to Rollbase URL fields.
• You can now 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 now checks for the maximum number of fields allowed for each data type before creating fields.
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.
• Rollbase now reads each table description in Access and saves it as the object description.
See Creating a Rollbase application from Microsoft Access for details and an example.

Support for new currency formats

Rollbase 4.3 now supports the following currency formats:
• Saudi Arabian Riyal
• Iranian Rial
• Kuwaiti Dinar
• Iraqi Dinar
• Tunisian Dinar
• Algerian Dinar
• Jordanian Dinar
• Qatari Riyal
• United Arab Emirates Dirham
• Moroccan Dirham
See Currency formats on page 807 for details.
New option for Send Email workflow action supports one-click email
A new option for the Send Email workflow action, Perform action without opening a new page, allows users
to send an email immediately by clicking the action without opening a new page. See Send Email action on
page 420 for more information.
Ability to set and get login permission for the Customer object in Rollbase Private
Cloud using REST APIs
Master administrators can now set Login permission on the Customer object definition using REST APIs. The
following APIs are affected:
• setPermissionsByRole, setPermissionsByUser — The permissions URL parameter now allows
login as an option when entityType is object and entityId evaluates to Customer.
• getPermissionsByRole, getPermissionsByUser — The response will include the Login permission
for the Customer object if it is set for the specified role or user.
See the following for details:
• setPermissionsByRole on page 1277
• setPermissionsByUser on page 1278
• getPermissionsByRole on page 1246
• getPermissionsByUser on page 1247
PDML4 PDF converter now bundled with Rollbase Private Cloud

Prior to this release, you had to download and install the PDML4 PDF converter to have PDF rendering capability.
In this release, PDML4 version 3.9.9 is distributed with Rollbase Private Cloud.

The System tab of the System Console in Rollbase Private Cloud includes additional
information
The System tab of the System Console now includes information about each host running a server, including
its hostname and IP address, processor, operating system, Java version, RAM, and memory consumption. It
also includes a shared.properties tab to view the values of all shared properties. See Monitoring system
components on page 857 for more information.
New preference to turn off welcome emails

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.
To set the preference:
1. Navigate to Setup Home.
2. From the Administration Setup area, select Preferences.
3. Select the Turn off Welcome Email check box to enable silent onboarding. If deselected, Rollbase will
send welcome emails to new users.

Additional information about the latest backup file and backup history included on
Backup page
This release includes new information on the Backup page, including:
• A Directories Included column for the latest backup
• A Backup Activity Trail table that displays information about the latest backup and previous backups,
including the Backup File, Files Included, Notes, Status, and Start Date. Earlier versions required you
to click View Backup Log to find any information about previous backups.
The screen below shows the Backup page for version 4.2:
The following screen shows the Backup page for version 4.3:

Import jobs now run on Production server

Prior to Rollbase version 4.3, when you imported data from XLS/XLSX or CSV files, the import job was run on
the Storage server. In Rollbase version 4.3, import jobs are now run on the Production server. This addresses
some issues that arose when running import jobs on the Storage server:
• 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.
New behavior for removeAllSessionData APIs

The removeAllSessionData APIs now return OK even if there was no session data to remove:
• rbv_api.removeAllSessionData() on page 1063 — Always returns the string OK
• rbf_removeAllSessionData() on page 1149 — Always passes the string OK to the callback function (if one is
supplied)
New client-side API rbf_getPageTabIndexByName(name)

The client-side API rbf_getPageTabIndexByName(name) returns the page tab index for the specified page
tab name. If there is more than one tab with the same name, it returns the first tab index for the tab with that
name. Indexes start at 0. The tab name comparison is case insensitive.
New shared property EmailEncodings

In Rollbase version 4.3, the default email encoding is UTF-8. The shared property EmailEncodings controls
the default. Its value is a comma-separated list of encodings. The first item in the list is the default encoding.
The default value is UTF-8,ISO-8859-1,US-ASCII. To override the default on Rollbase Private Cloud, set
this property's value to a comma-separated list of encodings with the encoding you want as the default first,
for example, ISO-8859-1,UTF-8,US-ASCII.
See shared.properties on page 926 for more information about shared properties.
Element CustWeight from components.xml is now a shared property

The element CustWeight is now a shared property in the shared.properties file. See shared.properties
on page 926 for details.
Single click login deprecated

Single click login enabled users to open links to Rollbase application pages sent in Rollbase-generated emails
without logging in in certain circumstances. This capability is now deprecated.

Rollbase Mobile App Builder deprecated

Rollbase Mobile App Builder is deprecated and will not be developed further. The back-end service will continue
to be available to support existing apps.
Instead of using the Mobile App Builder for new apps, you can use Rollbase's enhanced features for mobile
device support or the integration with Telerik Platform. See Supporting mobile users on page 621 for more
information.

• New shared property HTTPReadTimeOut
New shared property HTTPReadTimeOut

This property specifies the length of the HTTP read timeout in Rollbase triggers. Defaults to 20000 milliseconds
in the shared.properties file. If this property is not present, its value is interpreted as 0, which means an
indefinite timeout value. See shared.properties on page 926 for more information about shared properties.


• User interface improvements on page 148

• Migrating original ID generation to GUID on page 178
• Microsoft Exchange integration
• Shared property updates for new email options
• Support for non GUI Rollbase Private Cloud installation
• Support for SAML authentication on Rollbase Private Cloud
• Support for generic JDBC based external tables (Beta)
• Session timeout notifications
• Enhancements to field-level permissions
• Improvements to Private Cloud white labeling
• New profile photo field for User object
• New server-side session data APIs
• New getIdByOriginalId APIs
• Tokens for API authentication
• New parameters for bulkCreate, bulkCreateOrUpdate, and bulkUpdate REST methods
• REST method bulkDelete now supports POST HTTP method
• New parameter useLegacyDateFormat for client-side query APIs that return dates
• New custom event on jQuery Growl messages
• New options for portals
• New shared property MaxSyncImportFileSize
• Setting default values using New page's onload script no longer marks the page as dirty
• External JavaScript libraries are no longer loaded multiple times
• New bulk action Sync Subscribers in Rollbase Private Cloud master tenant
• OpenEdge SPA authentication on Private Cloud now supports security questions for login
• Automatic creation of localization settings for customers switching from Classic UI to New UI
• Support for OpenEdge version 11.6.1 and PAS version 2.0
• Updates to third party libraries in Rollbase Private Cloud

Microsoft Exchange integration

Rollbase 4.2 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 Third Party Settings page on page 793 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= username@companyname.com
3. MailPassword=myPassword
See shared.properties on page 926 for more information.
You can also configure Rollbase to send administrative emails from an Exchange account during a Rollbase
Private Cloud installation.
Shared property updates for new email options

There are now three email options you can configure in Rollbase: SMTP, Exchange, and Gmail. To support
these options, the following shared properties have been modified:
• MailHost — This property now specifies the email option. For Exchange and Gmail, the value should be
Exchange or Gmail. For SMTP, the value should be the SMTP host name.
• MailPort — This property is only valid for SMTP.
• MailUseSSL — This property is only valid for SMTP.
• MailUser — This property is only valid for SMTP and Exchange.
• MailPassword — This property is only valid for SMTP and Exchange.
• MailTimeoutSec — This property is only valid for SMTP and Gmail.
The following shared properties are new:
• GoogleUserName — The gmail email address, for example, example@gmail.com.
• GoogleRefreshToken — Used to provide a refresh token for Gmail email settings. The token can be
obtained by using Google auth.

Support for non GUI Rollbase Private Cloud installation

Rollbase Private Cloud now supports two new installation modes in the installer:
• Console mode — Runs the installer in text-only mode.
• Silent mode — Enables an installer to run without any user interaction.
See Using the Rollbase installer on page 837 for more information.
Support for SAML authentication on Rollbase Private Cloud

Rollbase Private Cloud now supports Security Assertion Markup Language (SAML) authentication. Progress
has verified this support using Onelogin, Salesforce, OpenAM (Progress ID), and PingOne. See SAML/ADFS
authentication details on page 891 for more information.
Support for generic JDBC based external tables (Beta)

Rollbase Private Cloud 4.2 supports generic based external tables without Rollbase schema. This is beta
functionality in this release. This feature lets you create external object definitions from tables in MySQL,
OpenEdge RDBMS, Microsoft SQL Server, and Oracle Database. The tables can be in a remote database that
is not used as the Rollbase database. Like external objects created using other methods (DataDirect Cloud
and external tables in a Rollbase system schema), the schema and record data remains in the remote database
but in most cases behaves like native Rollbase data. See External object overview on page 693 for uses and
limitations of external objects.

The general steps for creating external objects using this feature are:
1. From an application menu, click the plus sign.
2. From the What do you want to create? dialog, select a new Object (with Tab) from External Metadata.
3. For Import From, select Remote Database.
4. On the Import from Remote Database page, select the database type and fill in the connection details:
5. On the Create Object page, select a table from the schema and define a singular and plural name.

6. On the Create Fields page, map table columns to fields in Rollbase objects.
After this step, you have successfully created an external Rollbase object from an external database schema.

Session timeout notifications

This release introduces notifications for two types of session timeouts:
• 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
Previously, the user would receive no warning that a session was going to expire. Now, Rollbase displays a
warning (by default, five minutes before the timeout) that the session is going to expire. For an inactive session,
the user can click Extend Session to reactivate the session or click Log Out to log out of Rollbase. The user
can also perform an action in the application's user interface to extend the session. For a session timeout that
requires the user to re-login, the user can click Log Out to log out immediately or wait until the session expires
to re-login. The warnings are displayed across all tabs and windows in which the user is logged into Rollbase,
and extending a session extends the session across all tabs and windows in which the user is logged into
Rollbase.

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.
• 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.

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 securityLevel.xml on page 924 for details.
The PageContext on page 1156 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.
Enhancements to field-level permissions

Field-level permissions now include the following enhancements:
• Field-level edit permission is now granted for any activity that creates or updates records, including Edit
pages, New pages, Quick Create pages, Mass Update pages, and inline editing.
• For required fields, field permission takes precedence over the required value validation. For example, if a
user’s role does not have permission to edit a required field, but they can create a record of that type, they
will not be allowed to put a value in the field, but they will be able to save the record with an empty required
field.
See Setting field-level permissions on page 737 for more information.
Improvements to Private Cloud white labeling

This release includes additional improvements to Private Cloud white labeling. Rollbase version 4.04 included
the improvements described here: Improved support for white labeling in Rollbase Private Cloud. For version
4.2, inline CSS styling has been removed from the files listed below and put into a new file,
<rollbase_install_dir>\Pas_Instance\webapps\router\css\rbcommon.css (if using PAS) or
<tomcat-install-dir>\webapps\router\css\rbcommon.css (if using Tomcat).
Hooks have been added to the files listed below so that you can customize styles and/or behavior using custom
CSS and JS files. You can place these files in the personalize folder, located at
<rollbase_install_dir>\Pas_Instance\rollbase\personalize (if using PAS) or
<tomcat-install-dir>\rollbase\personalize (if using Tomcat). Put custom JS files in a folder named
js under the personalize folder. Put custom CSS files in a folder named css under the personalize
folder. Rollbase will automatically use your custom files to override the default styles and/or behavior.

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
• router\login\activate.jsp — The custom password reset page
• master(or prod1)\components\loginExpired.jsp — The custom login expired page
Note: In the logout.jsp file, the code that displays HTML content after a logout was removed in Rollbase
version 4.0.4.
New profile photo field for User object

A new system field of the type Image Upload field, User Profile Pic, has been added to the User object.
If you previously created a different field in the User object for a profile picture, you can copy the image from
that field to the User Profile Pic field in one of the following ways:
• From the field view page, select Copy from the More actions menu:
• From the Fields section of the object definition page, click Copy in the field's row:

The Profile Photo: Copy page opens. From the Target drop-down, select User Profile Pic:
The images from the Source field are copied into the Target field for all User records, up to the maximum
number defined by the shared property MaxReqsInQuery (Configurable in Rollbase Private Cloud; defaults
to 20,000).
New server-side session data APIs

Rollbase v4.1 introduced setting and accessing custom session data using client-side APIs. This release
introduces server-side APIs that serve the same purpose.
The new APIs are:
• rbv_api.setSessionData(key, value) — Stores session data as key/value pair
• rbv_api.getSessionData(key) — Retrieves the value for the specified key
• rbv_api.getAllSessionData() — Retrieves all key/value pairs for that user
• rbv_api.removeSessionData(key) — Removes the session data for the specified key
• rbv_api.removeAllSessionData() — Removes all session data for the user
For details and examples, see User session data API on page 1059.
New getIdByOriginalId APIs

This release introduces three new APIs that, given an entity type and an original ID, return the entity's ID:
• getIdByOriginalId on page 1242 — REST method
• rbv_api.getIdByOriginalId() on page 1028 — Server-side API
• rbf_getIdByOriginalId() on page 1125 — Client-side API
Tokens for API authentication

Rollbase Private Cloud now supports using tokens for authentication in login APIs instead of the user's password.
This feature is available for all authentication methods except for OpenEdge SPA and custom authentication.
To use tokens for authentication, an administrator must first enable them for the tenant. See Enabling tokens
for API authentication on page 897 for details.
After API authentication tokens have been enabled, you can generate the token on your My Preferences page.
See My Preferences page on page 794 for details.
The authentication mechanism can also be set globally using the APIAuth shared property. See shared.properties

For general information about API authentication, see API authentication on page 897.
New parameters for bulkCreate, bulkCreateOrUpdate, and bulkUpdate REST methods

The REST methods bulkCreate on page 1217, bulkCreateOrUpdate on page 1218, and bulkUpdate on page 1221
now support two additional parameters:
• importMode — Specifies the import mode. Can be one of 0 (normal), 1 (test), or 2 (bulk).
• createAction — Boolean that specifies whether to set picklist values while importing. When true, picklist
values are set. When false, picklist values are not set. The importMode parameter must be 0 or 1 for
picklist values to be set.
REST method bulkDelete now supports POST HTTP method

To enable deleting a large number of records (more than 1500), the bulkDelete REST method now supports
the POST HTTP method. See bulkDelete on page 1220 for more information about this method.
New parameter useLegacyDateFormat for client-side query APIs that return dates
A new, optional, Boolean parameter, useLegacyDateFormat, is available in client-side query APIs that return
dates in JSON format. This parameter specifies whether date values returned by the API are returned as new
Date objects or as Strings. If this parameter is true, or if it is not passed, date values are returned as new
Date objects. If this parameter is false, date values are returned as Strings. The APIs where you can use
this parameter are:
• rbf_selectQuery() on page 1084
• rbf_selectQuery2() on page 1085
• rbf_selectValue() on page 1087
New custom event on jQuery Growl messages

A new custom event, rb.newui.util.customEvents.rbs_notificationDisplayed, is now available.
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
See Custom events on page 1169 for an example that illustrates how to add an event listener and handler for
this event.
New options for portals

Three new options are available for portals:
• Use Bootstrap v3 — Previously, only Bootstrap 2 files were used for Rollbase portals. When you create
or edit a portal, you can check the Use Bootstrap v3 check box to add Bootstrap 3-related CSS and JS
files for the portal. Note that when Bootstrap v3 is included, Bootstrap v2 is not included.
• 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 in this release.
The screen below shows the new options:
New shared property MaxSyncImportFileSize

When importing data from an Excel or CSV file, the shared property MaxSyncImportFileSize specifies the
maximum size, in bytes, for which the import will be in synchronous mode. Files above this size will be imported
in asynchronous mode. Defaults to 20480 bytes.
Setting default values from New page's onload script no longer marks the page as
dirty
Prior to this release, setting field values from a New page's onload script incorrectly marked the page as dirty.
In Rollbase 4.2, this no longer marks the page as dirty. Note that updating fields from a user action that executes
a script, such as clicking a button, does mark the page as dirty.

External JavaScript libraries are no longer loaded multiple times

Previously, external JavaScript references were reloaded multiple times, even with Ajax navigation turned on.
To prevent this, Rollbase 4.2 now adds an external JavaScript library to a registry when it is loaded. When its
external script tag is encountered again, the JavaScript definitions are not reloaded. Once loaded, the JavaScript
definition is always available. This has been implemented for external libraries that Rollbase uses, such as
FusionCharts, Google Charts, and Google Maps.
If your code contains any callback function configured to execute when an external library is loaded, this code
will not execute if the library is already loaded. The solution to this is to check whether the library is loaded,
and explicitly execute the callback function if it is already loaded.
The following code is a custom script component that illustrates how to load an external library configured with
a callback handler:
<script src="https://www.google.com/jsapi?autoload={'modules':[{'name':'visualization',
'version':'1','packages':['corechart','table']}]}" ></script>
<script type="text/javascript">
if (window.google.visualization)
{
drawChart();
}
else
{
google.load("visualization", "1", {packages:["corechart"]});
google.setOnLoadCallback(drawChart);
}
function drawChart() {
//draw chart on google chart api load…
}
New bulk action Sync Subscribers in Rollbase Private Cloud master tenant
A new bulk action, Sync Subscribers, is now available on master tenants for Rollbase Private Cloud. This
action syncs subscriber records with user records. For example, it is possible for a user record to be deleted
but that user still appears in the list of subscribers.
When you execute this action:
• The message Sync subscribers process has begun appears on the page. The process runs in a
background thread.
• Existing subscriber records are updated with correct user data.
• Missing subscriber records are created using data from the related user.
• Any orphan subscriber (a subscriber with no related user record) is deleted.
The action writes its activities to the log file subscriberSync.log. To view the log, click System > Master
Zone and click Master Server Logs.
You can execute this action from the System Console application, either from the Customer List section of
the Customers tab or from the Customer View page:

This action is only available to administrators on the master tenant.

OpenEdge SPA authentication on Private Cloud now supports security questions for
login
When configuring OpenEdge SPA authentication on Rollbase Private Cloud, you can now configure security
questions for users to answer when they log in. See OpenEdge authentication details on page 886 for information
about configuring OpenEdge SPA authentication. See Security questions for authentication on page 898 for
general information about security questions. See Configuring security questions on page 898 for details about
configuring security questions.
Automatic creation of localization settings for customers switching from Classic UI

to New UI
The New UI depends on localization settings being present in the tenant. Prior to this release, if you had been
using the Classic UI and moved to the NewUI, an administrator would have to manually create localization
settings at the tenant level on the Localization Settings page.
Now, when the New UI is enabled for any set of users, Rollbase automatically creates localization settings for
the tenant.
Note: Going back to the Classic UI will not cause the localization settings to be deleted. If you require deletion
of the localization settings, you will have to do it manually on the Localization Settings page.
Support for OpenEdge version 11.6.1 and PAS version 2.0

Rollbase Private Cloud version 4.2 now supports OpenEdge version 11.6.1 and PAS version 2.0. See Platforms
supported for Private Cloud on page 833 for details about all supported software.
Updates to third party libraries in Rollbase Private Cloud

Rollbase Private Cloud 4.2 includes the following changes to third party libraries:
• FusionCharts and FusionWidgets are now included in Rollbase Private Cloud and it is not necessary to
install them.
• The StelsMDB Access JDBC driver has been replaced by an alternative library included in Rollbase Private
Cloud.
• While you can still install Aspose.Words for Java and Aspose.Pdf for Java, alternative library-based
implementations are now included in Rollbase Private Cloud. If an Aspose library is found in the path, it will
take precedence.
See Third party software you can install on page 835 for more information about third party libraries.
User interface improvements

Rollbase 4.2 contains many updates to the user interface and greatly improved support for mobile devices.
Improvements in this release include the following:
• UI blueprints
• Custom icons for tabs in Modern - Vertical Menus blueprint
• Ability to place labels above field values
• Live Preview
• Cards and card containers
• The card editor

• Vertical responsive design

• Ability to make views available per device
• Image carousel
• Responsive charts
• Responsive images now enabled by default
• Support for right-to-left text direction (experimental)
• Support for selecting multiple records on Selector pages for lookup fields
• Responsive dashboard pages
• Replaced file upload component with Kendo upload widget
UI blueprints (experimental)
A new application-level setting allows 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. For example,
the existing blueprint, now called Traditional, has a sidebar (collapsed by default), a header, which includes
the application switcher and the application tabs and menus, and a footer:
The new blueprint, called Modern - Vertical Menus, 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.
Note: The Modern - Vertical Menus blueprint is experimental in this release.

The following screen shows the Modern - Vertical Menus blueprint with the application switcher selected.
The following screens show the Modern - Vertical Menus blueprint on a desktop in its two states. Open the
sidebar by clicking the hamburger menu at the top left of the screen. Expand or collapse the sidebar by clicking
the hamburger menu.


The following screen shows the Modern - Vertical Menus blueprint on a smart phone.

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, select the UI blueprint from the UI Blueprint drop-down menu:

4. Click Save.
You can also set the UI blueprint for an application using Live Preview.
The UI blueprint for each application appears in the application list on the applications setup page:
Custom icons for tabs in Modern - Vertical Menus blueprint (experimental)

If your application is configured to use the Modern - Vertical Menus UI blueprint, the icons in the sidebar tabs
are rendered 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:

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:

To configure an individual tab to use a custom image as its icon:

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:

Ability to place labels above field values

You can now configure, at the application level, that labels are rendered above field values on certain types of
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:

The following screen shows an application page with labels above field values on a smart phone:
Live Preview
Live Preview is a tool where you, as 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.
To open Live Preview, do one of the following:
• If you are using the Traditional blueprint, click Live Preview from the Rollbase menu:

• If you are using the Modern - Vertical Menus blueprint, expand Administration in the sidebar and click
Live Preview:

Live Preview lets you select options for the following:

• 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 for more information.
• The theme for the application. See Working with themes on page 578 for more information about themes.
• The field label setting. This specifies whether to place field labels to the left of field values or above field
values based on the device. See Editing applications on page 274 for more information about field label
settings.
• The card templates used to display record lists on different mobile devices. See Cards and card containers
for more information about cards.
• Toggle the text direction. See Support for right-to-left text direction for more information about text direction.
Click the thumbs-up icon to save your changes or click the X icon to discard your changes and close Live
Preview.
The following screen shows the Live Preview interface. In this example, the user has selected the smart phone
interface, selected a different theme, and selected a user-defined card:

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:

Cards and card containers

Cards and card containers are a new way 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, and is a vertical,
scrollable list of cards. It supports infinite scrolling as well as touch gestures. By default, a card container will
render with the default card, which displays the record name and a way to drill down to individual records:
You can create your own cards using the card editor.

The card editor (experimental)

The card editor allows you to create and edit cards for displaying in card containers on mobile devices. The
card editor is designed to be very flexible. There are four ways you can 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:
1. Decide which object type for which you want to create the card and open a record list page for that object
type.
2. Open Live Preview and select a mobile device.
3. Click + Create a New Card:
4. 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:

5. Select the device for which you want to create the card. you can select smart phone, tablet in portrait mode,
or tablet in landscape mode.
6. If you selected a design, click Next and map components in the card to fields. If you selected a layout, click
+ Create a New Card and edit the card in the card editor
7. 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 opens for the card.

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 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.
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.

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 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
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 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 Tools sidebar includes the following tools:

• Label and Value — Lets you add field labels and values to the card. Place the cursor where you want to
add a label or value and select the label or value from the drop-down list.
• 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.

• 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.

At any time while editing a card, you can click the view HTML button to view the HTML source:

The HTML source editor opens:
You can edit the HTML source in this editor or you can copy the HTML source and edit it in a different HTML
editor.
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.

Vertical responsive design

Rollbase version 4.2 now supports vertical responsive design as the default responsive mode. You can still
select horizontal responsive design, which was mode introduced with the New UI for version 4.0, at the application
level. See Editing applications on page 274 for details.
Responsive design is geared towards providing optimal viewing of apps on a variety of devices. For a Rollbase
app, you can design pages such as View, Create, 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.
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:
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.
Ability to make views available per device

A new option, Show In, is available when creating or editing a view. This option allows you to select the types
of devices (desktop, tablet, smart phone) for which the view is available.
The following rules apply:

• By default, existing views are available on desktops and tablets but not on smart phones. This is because
it is unlikely that the view was created with smart phones in mind. 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.
The setting selected for each view appears in the Show In column of the Views table on the object definition
page:
See Creating and editing views on page 561 for more information about creating and editing views.

Image carousel
When an object definition contains multiple image fields, you can configure Rollbase to group 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.
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. See Responsive images now enabled by default for information about configuring image
responsiveness and maximum width.
The following screen shows an image carousel on a desktop. You can use the arrows to browse through the
images.

The following screen shows the same image carousel on a smart phone. On all mobile devices, you can swipe
left or right to browse through the images or you can use the arrows.
Image carousels are disabled by default to remain compatible with existing page layouts. To enable image
carousels for an application, set the property
rb.newui.options.useCarouselWhenMultipleImgFieldsInObject to true in a custom header
script or a custom sidebar script.
Responsive charts
Charts are now 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 471 for more information.

Responsive images now enabled by default

When responsive image fields were introduced in Rollbase 4.0.6, responsiveness was disabled by default. In
this release, responsive images are enabled 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.
Note: The property rb.newui.options.useResponsiveImage was introduced in Rollbase 4.0.6 to control

image responsiveness. This has been deprecated in version 4.2 because image responsiveness is now
controllable in the page editor. See useResponsiveImage on page 1169 for more information.
Right-to-left text direction (experimental)

Right-to-left text direction is now available as an experimental feature for an application or for a portal. This is
intended for languages that are written from right to left, such as Arabic or Hebrew.
To configure right-to-left text direction for an application, select the Right to Left Text Direction check box
when editing an application. See Editing applications on page 274 for more information.
To configure right-to-left text direction for a portal, select the Right to Left Text Direction check box when
creating or editing a portal. This property is only enabled if either Use Bootstrap v3 or Include Kendo UI is
selected. See Creating a portal on page 596 for more information.
Support for selecting multiple records on Selector pages for lookup fields
When a page includes a lookup field for an n-to-many relationship, the Selector page now supports selecting
multiple records. The page contains a check box for each record that is not already attached to the lookup field.
This filtering remains in effect even if you change the view or search for records. When at least one record is
selected, an Attach Selected button is enabled on the page.

When a lookup field is for an n-to-one relationship, the selector page does not contain check boxes and works
as before.
Selecting multiple records on Selector pages is only available when using the New UI.
Note: When you select a lookup field from a grid control, the resulting Selector page supports selecting multiple
records, but does not filter out records that are already attached to the lookup field.
The following screen shows the new interface for selecting multiple records:
Responsive dashboard pages

Rollbase 4.2 supports responsive generic pages (pages you create from generic tabs; see Creating tabs and
pages on page 490) with a fallback mechanism to revert to the way the Classic UI and the New UI (up to version
4.1) rendered them (fluid). Generic pages are frequently used 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.
Replaced file upload component with Kendo upload widget

The interface for uploading files to File Upload and Image Upload fields now uses the Kendo upload widget as
shown below:
Migrating original ID generation to GUID

Starting with Rollbase version 4.2, Rollbase is moving away from the 64 bit auto-incrementing integer based
Original ID to a 128 bit based random GUID. A GUID is a Globally Unique Identifier, also known as a Universal
Unique Identifier that enables uniquely identifying any given resource across various Rollbase deployments.
The 128 bit space is so large that it brings down the probability of two randomly generated GUIDs being the
same to negligible.

All Original IDs for metadata and data will be GUIDs stored as Base64 encoded Strings. This affects the
following areas:
• Database schema — Upgrade required; see Updating the database schema.

• APIs — Updates to API calls might be required; see API updates.
Note: There will be absolutely no effect on any existing application developed on earlier versions of Rollbase,
as the platform is designed to support the existing integer Original IDs. There will be no change to metadata
and data stored in the database and no representational changes on the UI after a v4.2 upgrade. Your apps
will continue to run as they were without any impact. However, you should update the database schema using
the update script, following the procedure described in Updating the database schema.
Updating the database schema

All database table definitions that defined Original ID as Integer have been changed to CHAR(22). There will
be an update script available for migrating from an older Rollbase version to version 4.2. There is no impact
on indexes due to this change.
When upgrading the database schema for your Rollbase tenant, please do the following:
• Take a backup of the database before running the update script.

• Store the result/log of the update script execution for future reference.
For Rollbase Private Cloud customers using Open Edge, note that the OpenEdge database does not support
modifying the data type of an existing column using the SQL ALTER statement with a MODIFY. Therefore, the
chosen method implemented in the update script is the following, which means a slightly longer downtime for
the database update:
1. Create a temporary column.
2. Copy the data from the existing Original ID column to the temporary column using the CAST function.
3. Drop the existing Original ID column.
4. Rename the temporary column as Original ID.
API updates
If you use the Rollbase APIs, you will have to make changes (if necessary) to not assume that the Original ID
is an integer value. Progress has identified these APIs and fixing them should be very straightforward. If you
have written a client that calls any Rollbase APIs that assume the Original ID is an integer, either as a parameter
or in the response, you will need to fix them to use String instead. In addition, you will have to recompile all
SOAP clients using the version 4.2 api.wsdl and metadata.xsd to ensure things work seamlessly in
Rollbase 4.2. These files are available from the following locations:
• api.wsdl: https://www.rollbase.com/webapi/wsdl/api.wsdl; also see Rollbase SOAP Methods on page 1285.

• metadata.xsd: https://www.rollbase.com/webapi/wsdl/metadata.xsd; also see Metadata API and XML
Reference on page 1173.
There is no change required if you are not using any of the following affected APIs:
Type API Description

Server-side rbv_api.getCount() on page 1003 Accepts Original ID as input
Server-side rbv_api.runTrigger() on page 1020 Accepts Original ID as input
Server-side rbv_api.startApproval() on page 1022 Accepts Original ID as input
Server-side rbv_api.isAppInstalled() on page 1026 Accepts Original ID as input


Server-side rbv_api.runReport() on page 1030 Accepts Original ID as input
Server-side rbv_api.runTemplate() on page 1031 Accepts Original ID as input
Server-side rbv_api.getHostedAsText() on page 1038 Accepts Original ID as input
Server-side rbv_api.getHostedAsBinary() on page Accepts Original ID as input
1039
Server-side rbv_api.getRoleById() on page 1029 Accepts Original ID as input and returns
Original ID in response
Client-side rbf_getCount() on page 1066 Accepts Original ID as input
Client-side rbf_getCount2() on page 1067 Accepts Original ID as input
Client-side rbf_getPage() on page 1070 Accepts Original ID as input
Client-side rbf_getPage2() on page 1072 Accepts Original ID as input
Client-side rbf_runTrigger() on page 1081 Accepts Original ID as input
Client-side rbf_getApplicationDef() on page 1117 Accepts Original ID as input and returns
Client-side rbf_deleteApplicationDef() on page 1114 Accepts Original ID as input
Client-side rbf_getFieldDef() on page 1118 Returns Original ID in response
Client-side rbf_getObjectDef() on page 1118 Returns Original ID in response
Client-side rbf_getRelationshipDef() on page 1119 Returns Original ID in response
REST getCount on page 1237 Accepts Original ID as input
REST getPage on page 1244 Accepts Original ID as input
REST runTrigger on page 1263 Accepts Original ID as input
REST bulkUpdate on page 1221 Accepts Original ID as input
REST bulkCreate on page 1217 Accepts Original ID as input
REST bulkCreateOrUpdate on page 1218 Accepts Original ID as input
REST getRoleById on page 1253 Accepts Original ID as input and returns
REST getPermissionsByRole on page 1246 Accepts Original ID as input
REST setPermissionsByRole on page 1277 Accepts Original ID as input
REST getPermissionsByUser on page 1247 Accepts Original ID as input
REST setPermissionsByUser on page 1278 Accepts Original ID as input
REST getApplicationDef on page 1208 Accepts Original ID as input and returns
REST deleteApplicationDef on page 1206 Accepts Original ID as input
REST getRoles on page 1254 Returns Original ID in response
REST getFieldDef on page 1210 Returns Original ID in response
REST getObjectDef on page 1210 Returns Original ID in response
REST getRelationshipDef on page 1212 Returns Original ID in response


SOAP getCount() on page 1303 Accepts Original ID as input
SOAP getPage() on page 1308 Accepts Original ID as input
SOAP bulkCreate() on page 1289 Accepts Original ID as input
SOAP bulkCreateUpdate() on page 1289 Accepts Original ID as input
SOAP bulkUpdate() on page 1290 Accepts Original ID as input
SOAP getApplicationDef() on page 1196 Accepts Original ID as input and returns
SOAP deleteApplicationDef() on page 1193 Accepts Original ID as input
SOAP getFieldDef() on page 1196 Returns Original ID in response
SOAP getObjectDef() on page 1197 Returns Original ID in response
SOAP getRelationshipDef() on page 1198 Returns Original ID in response

• New REST method runAction

• New shared property MaxSyncImportFileSize
New REST method runAction

The new REST method runAction runs a workflow action on a record. See runAction on page 1262 for details.
New shared property MaxSyncImportFileSize

When importing data from an Excel or CSV file in Rollbase Private Cloud, the maximum size, in bytes, for which
the import will be in synchronous mode. Files above this size will be imported in asynchronous mode. Defaults
to 20480 bytes. See shared.properties on page 926 for more information about shared properties.


• Transitioning to AJAX navigation

• AJAX tab navigation now includes sub-menus
• Enhancements to custom reports
• Landing page per user
• New client-side AJAX session data APIs
• Increase in maximum number of layers allowed in tabular reports
• New shared property MinExpirationPolicy
• OpenEdge SPA authentication enhancements for Rollbase Private Cloud
Transitioning to AJAX navigation

Rollbase 4.0.4 introduced support for more AJAX requests instead of full page reloads. Using AJAX requests
improves the performance on the client side (faster load and less data transferred) and on the server side
(better scalability). This capability was disabled by default for existing Rollbase customers, but is now enabled
by default for everyone.
To ease the transition to AJAX navigation, be aware of the following:
• If your applications contain any script components that execute on the document.ready event, they will
no longer behave in the same way. Instead, you should replace the document.ready event with a call to
addEventListener() on the rbs_pageRender custom event. See addEventListener() on page 1159 for
details and an example.
• If your application uses the onunload event on the Page Properties screen, note that this event will not
fire when using AJAX navigation. Because of this, and because it does not have good cross-browser support,
Progress recommends not using this event in your applications.
You can disable AJAX navigation by setting the following properties in a custom sidebar script that executes
before the UI starts:
• rb.newui.options.applicationPage.ajaxNavigation
• rb.newui.options.objectViewPage.recordNavigationAjax
• rb.newui.options.tabMenuLink.ajaxNavigation
AJAX tab navigation now includes sub-menus

All tab navigation, including sub-menus now uses AJAX calls. This will improve performance as header and
sidebar data is no longer roundtripped from the server when navigating through tabs. This enhancement applies
to object pages and generic pages; Web pages do not use AJAX tab navigation for sub-menus.
Enhancements to custom reports

This release includes the following enhancements to custom reports:
• The new Wizard section type — This section type uses a wizard that lets you select fields, sorting and
grouping, totals and subtotals, and report filters for the section. See Wizard section on page 462 for details.

• The CSS Stylesheet for a custom report can be a hosted file — See Creating custom reports on page 455
for details.
• Loop sections now use standard filtering — See Loop section on page 464 for details.
• The token Current Record (CURR_REC) is now Loop Record (LOOP_REC) — See Using tokens in custom
reports on page 465 for details.
• Improved user interface for generating tokens — See Using tokens in custom reports on page 465 for details.
Note: Custom reports are a beta feature in this release.
Landing page per user

By default, when you log in to Rollbase after logging out, the last page you visited opens and the last 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 733 for details. You can override these behaviors by configuring a landing page specifically for
your account on the My Preferences page on page 794. 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 page and menu that were open when you last logged out
• Assign Landing Page — The page and menu you select
New client-side AJAX session data APIs

Rollbase now supports setting and accessing custom session data. For example, if your application requires
visiting multiple pages and you want to view data on those pages that is all related to a single record, you can
store information about that record as session data and access it from each page using a script component on
the page.
The new APIs are:
• rbf_setSessionData(key, value, callback) — Stores session data as key/value pair
• rbf_getSessionData(key, callback) — Retrieves the value for the specified key and handles it
using the specified callback function
• rbf_getAllSessionData(callback) — Retrieves all key/value pairs for that user
• rbf_removeSessionData(key, callback) — Removes the session data for the specified key
• rbf_removeAllSessionData(callback) — Removes all session data for the user
For details and examples, see User session data on page 1144.

Increase in maximum number of layers allowed in tabular reports

Previously, tablular reports allowed up to three layers. Now tabular reports can have up to seven layers. Rollbase
Private Cloud administrators can set the maximum number of layers by setting the value of the shared property
TabularReportLayeringLimit. See Creating tabular reports on page 448 for more information about tabular
reports.
New shared property MinExpirationPolicy

The new shared property, MinExpirationPolicy, specifies the minimum number of days until a Rollbase
Private Cloud user's password expires on a non-master tenant. Defaults to 30. This property affects the
expiration policy for both password authentication and for OpenEdge SPA authentication.
OpenEdge SPA authentication enhancements for Rollbase Private Cloud

This release includes the following enhancements when using OpenEdge SPA authentication on Rollbase
Private Cloud:
• The ability for administrators to set the expiration policy, which is the number of days until a user's password
expires. This requires that the Manage Password property is enabled.
• The ability for administrators to create custom text for password guidelines. This text appears on the Change
Password page. This requires that the Manage Password property is enabled.
• For a failed login, error messages on the login page now include the reason for the failed login for locked,
disabled, and expired accounts.
• The REST methods setAuthentication and getAuthentication now support the following parameters
for OpenEdge authentication. The parameter managePassword must be true in order to set these using
setAuthentication:
• expirPolicy — The number of days until a user's password expires.
• passwordGuidelines — Custom text for password guidelines. This text appears on the Change
Password page.
See OpenEdge authentication details on page 886 for details about setting the expiration policy and custom
password guidelines. See setAuthentication on page 1269 and getAuthentication on page 1233 for details about
the above REST methods.

• Pagination control at top for record list components
• Sizing record list columns as an HTML table
• Responsive image fields
• Rollbase now remembers last used application and tab
• Role-based landing pages
• Ability to change uploaded file without changing its URL
• Support for additional currencies
• The login REST method now takes some parameters as HTTP headers

• New JavaScript API rb.newui.util.removeFieldLabel()

• New server-side API rbv_api.getRoleById()
• Additional page sizes for PDFs
• Conditional field-level permissions
• New administrative permissions for non-administrative roles
• New post install script for applications
• New shared property AllowAdminLessTenant
• Custom reports (beta)
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.
The following screen shows a Records List page with this property enabled:

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:

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:

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.

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
1169 for more information.
Rollbase now remembers last used application and tab

When a user logs out of Rollbase or times out, Rollbase saves the application and selected tab in the user's
preferences. When the user logs back in, Rollbase opens to that application and tab.
Note: If the user's role has a configured landing page, that landing page takes precedence. See Role-based
landing pages on page 189 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.

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.
Support for additional currencies

This release includes built-in support for the following currencies:
• Kazakhstani Tenge
• Belarusian Ruble
• Kyrgystani Som
• Moldovan Leu
• Ukrainian Hryvnia
• Bulgarian Lev

• Croatian Kuna
• Georgian Lari
• Romanian Leu
• Serbian Dinar
See Currency formats on page 807 for more information about currency formats.
The login REST method now takes some parameters as HTTP headers
For the login REST method, the parameters loginName, password, and custId can now be passed in HTTP
headers instead of as URL parameters. Passing these parameters as URL parameters is deprecated. You
should change existing code to pass these parameters as HTTP headers. The output parameter is still a
URL parameter. See login on page 1259 for more information.
New JavaScript API rb.newui.util.removeFieldLabel()

This API 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. See
removeFieldLabel() on page 1161 for details.
New server-side API rbv_api.getRoleById()

A new server-side API, rbv_api.getRoleById(), is now available. This API returns information about a
given role in JSON format, including the integration code, name, description, ID, and original ID of the role.
See rbv_api.getRoleById() on page 1029 for details.
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.

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:

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 1246 for details.

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 1277 for details.
For more information about field-level permissions, see Setting field-level permissions on page 737
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 194). 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.

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 194 for information about administrative
permissions for non-administrative roles.
See New post install script for applications on page 194 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 Creating custom reports on page 455.

• Filtering features on page 196

• Notification when user navigates from page with pending changes on page 198
• APIs to reload individual page components on page 199

• rbf_getPicklistCode() and rbf_getPicklistCodes() client-side APIs now work with other field types on page
199
• New getPicklistCode() method on FieldContext object on page 199
• New parameter to rbf_showOrHideField() on page 199
• JavaScript files available in uncompressed format on page 199
• Performance improvements when using OpenEdge Data Objects on page 200
• New REST methods on page 200
• New shared properties for password authentication on Rollbase Private Cloud master tenant on page 200
• Documentation updates for localization settings on page 201
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:

When this property is checked, the advanced filter options highlighted below will not appear on the page:

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 1168 for
details.
• The PageContext on page 1156 class method addDirtyPageNotifier() — Enables the notifications
• The PageContext on page 1156 class method removeDirtyPageNotifier() — Disables the notifications
A new PageContext on page 1156 method, isPageDirty(), returns true if the page has an object record form
with modifications.
See the newly documented JavaScript object PageContext on page 1156 and client-side method
rbf_getPageContext() on page 1135 for more information.

Note: This feature uses a built-in browser feature that is not supported on Safari for the iPad.
APIs to reload individual page components

Previously, when a record was modified by a client-side script, the only option to display changes was to reload
the entire page. You can now selectively reload chart, grid, and report components without reloading the entire
page. A new method on the JavaScript object PageComponent, refresh(), supports this behavior. A new
client-side ax API, rbf_getPageComponent(), returns the specified PageComponent. See the newly
documented JavaScript object PageComponent on page 1155 and client-side method rbf_getPageComponent()
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 getPicklistCode() method on FieldContext object

The FieldContext JavaScript object now has a getPicklistCode() method that returns either a single
integration code or an array of integration codes. This method works with the following field types: Picklist,
Picklist (Multi-Select), Group of Checkboxes, Radio Buttons. See the newly documented JavaScript object
FieldContext on page 1151 and client-side method rbf_getFieldContext() on page 1134 for more information.
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.
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.
New REST methods

The following REST methods are now available:
• getRoles — Returns a list of all the roles in the tenant in XML or JSON format
• getRoleById — Returns information about the specified role in XML or JSON format
• getPermissionsByRole — Returns information about all of the entities of the given type, including
permissions granted to the specified role
• getPermissionsByUser — Returns information about all of the entities of the given type, including
permissions granted to the specified user
• setPermissionsByRole — Sets the permissions for the specified role on the specified entity
• setPermissionsByUser — Sets the permissions for the specified user on the specified entity
• getAuthentication — Returns the authentication method for the tenant. This method is only available
for Rollbase Private Cloud.
• setAuthentication — Sets the authentication method for the tenant and returns a success/failure
response. This method is only available for Rollbase Private Cloud.
• licenseUpdate — Updates the license for a tenant
See Rollbase REST Methods on page 1216 for more information about Rollbase REST methods.
New shared properties for password authentication on Rollbase Private Cloud master
tenant
Two new shared properties for configuring password authentication on Rollbase Private Cloud master tenants
are now available:

• SecurityLevel — The security level, where 1 = low, 2 = medium, and 3 = high. See Setting and changing
security levels on page 877 for details about the different security levels.
• ExpirationPolicy — The number of days after which a user's password expires. A value of 0 means
no expiration; otherwise should have a value of at least 30.
These properties are automatically updated in the shared.properties file when an administrator changes
them on the Authentication: Password setup page. When an administrator changes these properties in the
shared.properties file, they are updated in Rollbase's database and the Authentication: Password setup
page reflects the new values after the server is restarted.
Documentation updates for localization settings

In the New UI, date and date/time formats for record list and view pages are obtained from the user's My
Localization Settings page. If these formats are not set, users can experience errors when trying to edit
records. The documentation has been improved to clarify how Rollbase uses these formats. In addition, the
documentation for the AJAX method rbf_formatDate() has been updated to show how to obtain the date
format from the user's localization settings. This uses the newly documented JavaScript object PageLocalization.
For more information, see:
• My Localization Settings page on page 793
• PageLocalization on page 1157
• rbf_formatDate() on page 1097

• Performance improvements for page reloads on page 202

• Support for Kerberos authentication in Rollbase Private Cloud on page 203
• Improved support for white labeling in Rollbase Private Cloud on page 204
• Built-in support for Dutch on page 205
• New client-side JavaScript API to identify type of current page on page 205
• New trigger timing options on page 206
• List in Selector pages is sized to fill the available space on page 206
• Ability to tailor the user interface based on device on page 206
• Filtering improvements on page 207
• Fields with input masks enforce mask during entry on new and edit pages on page 209
• Additional OpenEdge SPA credentials on page 209
• New shared property provides ability to use custom Java objects in formulas (Private Cloud) on page 210
• New parameter onlyViewFields in AJAX and REST getPage APIs on page 210
• Initial field focus on new/edit page load on page 211

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.
• 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.
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 4.0.4 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 351 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 4.0.4 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.

Support for Kerberos authentication in Rollbase Private Cloud

Rollbase Private Cloud customers can now use Windows Kerberos authentication. Setting up Kerberos
authentication requires the following:
• 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.
• Active Directory (AD) must be set up as described below.
• The shared.properties file must include the settings described below.
• Create new Customer(s) (tenants) as described below.
• Select Windows (Kerberos) as the authentication type as described below
• Browsers must be set up 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 properties KerberosDebug and KerbeosModuleName.
• 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.
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.
Improved support for white labeling in Rollbase Private Cloud

Rollbase 4.0.4 introduces 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
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
• master(or prod1)\components\logout.jsp — The custom logout animation page. Note that
the code that displays HTML content after a logout has been removed in Rollbase 4.0.4.
• master(or prod1)\components\loginExpired.jsp — The custom login expired page
Built-in support for Dutch

A Dutch translation of Rollbase UI text is now available. End users can select languages for their own account
and administrators can set them per tenant in Account Settings, see Language support on page 815 for more
information.
New client-side JavaScript API to identify type of current page

The new API rb.newui.page.PageContext.getPageType() returns the type of the current page. See
PageContext on page 1156 for details.

New trigger timing options

There are now two new trigger timing options:
• Before Restore: The trigger will run before a record is restored from the Recycle Bin.
• After Restore: The trigger will run after a record is restored from the Recycle Bin.
See Trigger timing options on page 384 for more information about trigger timing.
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 581 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.
Ability to tailor the user interface based on device

Administrators can tailor the user interface based on the type of device. Specifically, they can specify whether
specific instances of the following components are displayed on desktops, tablets, and/or smartphones:
• Tabs
• Page sections
• Buttons
The screens to create and edit these components each has the Show In option that allows you to specify
whether to display the component on each type of device:

Application and object definition setup pages that list tabs and buttons also show the display options for each.
For example, the screen below shows the display options for the tabs in an application in the Show In column.
In this example, the Reservations tab is not displayed on smartphones and the Chart tab is not displayed on
tablets or smartphones.
For more information, see the following topics:

• Creating a tab on page 299
• Adding and configuring sections on page 498
• Using buttons on pages on page 515
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:

• 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:

Use these flags in custom sidebar code as shown below:

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

You configure these credentials when configuring OpenEdge authentication:
New shared property 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
file. 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 926 for more information about shared properties.
New parameter onlyViewFields in AJAX and REST getPage APIs

The following APIs now include the Boolean parameter onlyViewFields. When true, the output only includes
fields that are in the specified view. When false, the output includes all fields in the object definition.
• The AJAX API rbf_getPage() on page 1070
• The AJAX API rbf_getPage2() on page 1072
• The REST method getPage on page 1244

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.

• Improved support for mobile devices

• New record list page options
• Customizing menus
• User changes to record list page are saved on a per view/per device basis
• Capability for end users to select theme preference
• Additional theme
• Enhanced page construction log
• Updated libraries
• Automatic addition of RTL (right to left) library
• Performance improvements
• New client-side JavaScript functions to detect mobile devices
• New CSS classes for mobile devices
• Updated CSS rule for Edge browser
• New Ajax API rbf_showOrHideField()
• New parameters for REST method createRecord
• New tcman server action showproc
• New features for OpenEdge integration
• Specify case sensitivity when connecting through DataDirect Cloud
• New Private Cloud AppInstallOverridesChanges setting
Improved support for mobile devices

Rollbase 4.0.3 includes 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.

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

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

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:

• 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:

• 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 581 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.

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.

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.
Capability for end users to select theme preference

In addition to administrators selecting a theme for a particular application, all users, including non-administrative
users, can now set a theme preference for all applications. For example, if an administrator sets the Room
Reservation application theme to Metro, a user of that application can set their theme preference to Material
and will see all applications, including Room Reservation, using the Material theme. Administrators can
disable this capability by setting Preferences from the Setup Home page. See Using the Theme Preview
mode on page 286 for details.
Note: This capability is only for the New UI; administrators must enable the New UI for all users
Additional theme
An additional built-in theme, Nova, is available in this release:
See Working with themes on page 578 for more information about themes.
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:
(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>
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 ]
Updated libraries
The following libraries have been updated:

Library name From version To version
Font Awesome 4.3.0 4.4.0
Kendo UI Professional 2015.2.624 2015.3.916
Bootstrap 3.3.4 3.3.5
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 1150 for more information.
New CSS classes for mobile devices

You can now 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 Custom CSS on page 581 for more information about customizing CSS.
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.
New Ajax API rbf_showOrHideField()

The new Ajax API rbf_showOrHideField() shows or hides a field and its label. See rbf_showOrHideField()
New parameters for REST method createRecord

There are two new parameters for the REST method createRecord:

• @p1 — When creating a User record, the password for the new user. This parameter is optional.
• @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.
See createRecord on page 1228 for details.
New tcman server action showproc

For Private Cloud installations that use the Progress Application Server (PAC), the new tcman server action
showproc (Windows only) shows information about the process specified by a process id. See Show Windows
process information (showproc) on page 972
New features for OpenEdge integration

When linking Rollbase external objects to OpenEdge Data Objects, the following features are now supported:
• The File Upload field type — The File Upload field type allows users to upload a file attachment that is
stored in this field. The file opens in a new browser window when clicked by the user. See File Upload field
• The Document Template field type — A Document Template field type is a picklist that allows users to
assign a document template to use for a specific object record. This field renders a link to generate a
document on the fly based on the selected document template using the record's data. See Document
templates on page 366 for more information about document templates. See Document Template Field on
page 1349 for more information about Document Template fields.
• The Document attribute — Objects with the Document attribute can store a file attachment.
• When you want to use the Document attribute for a Rollbase external object created from an OpenEdge
Data Object, you need to set the Document attribute after creating the Rollbase external object. The
Document attribute includes the fields Document File and Description. You will map OpenEdge fields
to these fields after setting the Document attribute. To accomplish this:
• When importing the OpenEdge Data Object definition, select Skip this Field for the field to be mapped
to the Document File field. You will map this after you set the Document attribute.
• When importing the OpenEdge Data Object definition, select Skip this Field for the field to be mapped
to the Description field. You will map this after you set the Document attribute.
See Object attributes on page 243 for more information about the Document attribute. See Linking Rollbase
external objects to OpenEdge data on page 662 for more information about creating Rollbase external objects
from OpenEdge data. See Enabling object attributes for an OpenEdge Data Object on page 676 for more
information about enabling object attributes from the OpenEdge side.
Specify case sensitivity when connecting through DataDirect Cloud

When integrating data from data source using DataDirect Cloud, you can now specify whether the target data
source uses case sensitive table and column names. See Using DataDirect Cloud to access external data on

New Private Cloud AppInstallOverridesChanges setting

At customer tenant creation, the AppInstallOverridesChanges property in the shared.properties
file controls whether conflicting application changes will be ignored or will override existing components. 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.

• Improvements in record view and record edit page toolbars on page 222
• Default font size and customization on page 223
• Page title customization on page 224
• Rollbase calendar improvements on page 224
• Mouse rollover opens actions menu on page 225
• Settings changed to Setup Home in Rollbase menu on page 225
• Workflow actions changed to picklist on page 226
• New placement of action controls for grids, charts, related records components, and reports on page 226
• Ability to remove header and footer from printed records on page 226
• Private Cloud shared.properties additions on page 226
• New Object Script API for cloning records on page 227
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:
• 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).
Default font size and customization

The default font size for application pages using the New UI is now 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. For example, the following style, if added to a custom header
or custom sidebar, results in a font size of 14px for 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.
For information about adding code to custom headers and sidebars, see Header and footer on page 283 and
Custom sidebar on page 283.

Page title customization

On record 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
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 */
*/
}
}
</style>
Rollbase calendar improvements

The Rollbase calendar has the following UI changes:
• Toolbar controls have been moved from within the canvas to the page header:
• 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.

Workflow actions changed to picklist

In record list views, available workflow actions are now rendered as a picklist:
New placement of action controls for grids, charts, related records components, and
reports
Controls for grids, charts, related records components, and reports have been reorganized for easier access
by users. See the following topics for details:
• Using a grid control on page 515
• Using charts on page 474
• Related records components on page 323
• Running reports on page 468
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; }.
Private Cloud shared.properties additions

New entries in shared.properties:
• EnableNUIForAll — When set to true, this property switches all of your tenants/customers to the New
UI in one step. The New UI is not enabled for all tenants/customers, as this property is not present in the
shared.properties file by default. If an administrator wants to enable the New UI for all tenants/customers,
this property must be added to the shared.properties file.
• NewOnlineHelpBaseUrl — Specifies the base URL that will be appended to context-sensitive Learn
More links in the UI for users of the new UI.
• CreateNewAppVideoURL — Specifies the URL to a user assistance video on how to create an application
using Rollbase quick create wizard.

• CustomizeAppVideoURL — Specifies the URL to a user assistance video on how to customize an

application using Rollbase.
• ShareYouAppVideoURL — Specifies the URL to a user assistance video on how to expose a Rollbase
application to end users.
• MaxSeedRecords — The maximum number of object records that can be attached to an application.
See shared.properties on page 926 for more details.
New Object Script API for cloning records

New API: rbv_api.cloneRecord() in the server-side Object Script API allows you to clone a record from
an existing one and override specific field values. See rbv_api.cloneRecord() on page 1017 for details.
Server-side and AJAX query APIs now work with OpenEdge Service objects
The following APIs are now supported to work with OpenEdge Service objects:
• rbv_api.selectNumber() on page 999
• rbv_api.selectQuery() on page 995
• rbv_api.selectQuery2() on page 997
• rbv_api.selectValue() on page 998
• rbf_selectNumber() on page 1083
• rbf_selectQuery() on page 1084
• rbf_selectQuery2() on page 1085
• rbf_selectValue() on page 1087

Rollbase 4.0 contains the following new features and enhancements:
• New user interface

• Capability to switch between the new UI and classic UI
• New Progress Rollbase Marketplace

• Integration with Telerik AppBuilder and Screen Builder
• New Quick Start Tutorial and Fast Track page
• Documentation enhancements
• New properties in the shared.properties file
• Documentation update for custom trigger development
New user interface

Rollbase 4.0 introduces a totally redesigned user interface (UI). The UI is responsive to different browser sizes,
uses a modern component framework (Kendo UI) with a rich set of widgets, and includes several built-in themes.

Highlights of the new UI include:

• A new page structure that no longer contains links at the bottom of a page, and there are no longer double
toolbars on view and edit pages.
• New headers and menus:
• Tabs now appear in a menu bar and are scalable, with an overflow menu for narrow browser windows.
See The application tab and menu bar on page 35 for details.
• A new hamburger menu (the Rollbase menu) replaces the sidebar. See The Rollbase menu on page
32 for details.
• A new page menu on record list pages provides easy access to the object definition and other
object-related functions. See The page menu on page 39 for details.
• A new Page Options menu provides easy access to page-related functions including the page editor.
See The Page Options menu on page 39 for details.
• New options for record list pages include end-user column selection that persists over multiple logins (see
Column data options on page 578), enhanced inline editing (see Inline editing on page 572), and the ability
to set the row height in the page editor.
• The Rollbase calendar, based on the Kendo UI scheduler widget, is responsive to different browser window
sizes. See The Rollbase calendar on page 260 for more information.
Benefits of using the new UI include the following:
• The responsive UI automatically adjusts itself for different screen widths and allows you to build applications
with a modern look that work well on a variety of devices. The responsive UI leverages the Bootstrap version
3 framework.
• 14 built-in themes, including two sets of complementary light and dark themes, allow greater flexibility in
the appearance of an application. See Working with themes on page 578 for more information.
• The new UI leverages Kendo UI widgets for controls and validation. Application developers who want to
customize the user interface for an application can use the full Kendo Professional Edition library. See the
Kendo UI documentation for more information.
• For existing customers, administrators can switch between the old UI (classic UI) and the new UI for selected
users to help with the transition to the new UI. See Capability to switch between the new UI and classic UI
for details.
• The new UI uses the Font Awesome toolkit, which provides scalable vector icons that you can customize
for size, color, and drop shadow, and for anything you can do using CSS. See
http://fortawesome.github.io/Font-Awesome for more information.
• More client-side processing in the UI results in fewer page reloads and better performance.
Capability to switch between the new UI and classic UI
Existing customers are configured to use the classic UI by default. Administrators can switch between the
classic UI and the new UI for selected users or for all users to help with the transition to the new UI. New
customers can only use the new UI.

To enable the new UI:

1. From the Setup home page, select Preferences under Administration Setup. The Preferences page
opens with options for enabling the New UI:
2. Select from the following options:

• New UI is enabled for me — Enables the New UI only for the logged-in administrative user. Select this
option to allow a specific administrator to test applications using the New UI without affecting other users.
• New UI is enabled for the following users — Enables the New UI only for the selected users. Select
this option to allow non-administrative users to test applications using the New UI without affecting other
users.
• New UI is enabled for everyone — Enables the New UI for all users. Select this option after all deployed
applications are verified to work with the New UI.
On Rollbase Private Cloud, administrators on the master tenant can control whether the above options are
available for newly created tenants via the property AllowClassicUIForNewTenants in the
shared.properties file. This property's default value is false. This property has the following effect:
• When false, all newly created tenants will be on the New UI and will not have an option change to the Classic
UI.
• When true, all newly created tenants will be on the New UI and will be able to use the options described
above to switch between the New UI and the Classic UI.
Progress Rollbase Marketplace

Progress Rollbase Marketplace is an online store for Rollbase applications, which can be offered free or for a
fee. Hosted Rollbase users can share applications they create on the hosted Marketplace, which can be
accessed by all Rollbase users. Rollbase Private Cloud master tenant administrators manage a Marketplace
for their customer tenants. For information about publishing and distributing applications on the Progress
Rollbase Marketplace, see Using the Progress Rollbase Marketplace on page 766.


Private Cloud master tenant administrators can choose between the Marketplace and the legacy Application
Directory as the application distribution mechanism for their users. However, Progress recommends the new
Marketplace because it offers more features and a better user experience. The MarketplaceURL property in
the shared.properties file controls whether Marketplace or Application Directory is enabled for all users
of a Private Cloud instance (see shared.properties on page 926). The administrator of a Private Cloud master
tenant can also rebrand Marketplace by adding a custom logo and configuring Marketplace settings. See
Rebranding Marketplace for details.
Integration with Telerik AppBuilder and Screen Builder

TM TM
Telerik AppBuilder and Screen Builder provide an integration with Rollbase, allowing you to quickly build
modern apps for mobile devices that access Rollbase application data. On the Rollbase side, you create a
Progress Data Catalog that exposes the objects to external sources and specify the location of the service that
will handle the calls from the mobile apps. For information about generating Progress Data Catalogs and using
them in Telerik AppBuilder, see Creating Progress Data Catalogs for external applications on page 717 and
Using the Telerik Platform to create a mobile app on page 622.
New Quick Start Tutorial and Fast Track page

To help new users get up to speed quickly, Progress has created a Fast Track page that features aQuick Start
Tutorial, which is separate from the regular documentation. The Fast Track page includes links to a new tutorial,
to user assistance videos, and to the documentation.

The new tutorial guides you through creating an application that allows you to practice using many features of
Rollbase, including:
• Setting up user accounts
• Using the Quick Create wizard
• Editing application pages
• Defining triggers
• Creating and editing views
• Customizing the user interface
• Configuring access control
You can access the tutorial from the Fast Track page or at
http://documentation.progress.com/output/rb/tutorial-qs/.
Documentation enhancements
Because the look of all application pages and procedures for some tasks differ between the new UI and the
classic UI, two documentation sets are available. The Help and Learn More links in Rollbase open the online
documentation set for the UI you are using. Rollbase Private Cloud will ship with the PDF version of the New
UI documentation. There will be no PDF version of the Classic UI documentation.
The two documentation sets have a different look and feel:
• Documentation for the classic UI:

• Documentation for the new UI:

However, even if you are using the classic UI, Progress recommends that you reference documentation on
the new UI for these reasons:
• The usability and completeness of the new UI documentation has been greatly improved.
• By consulting the new UI documentation, you can get an idea of what your application might look like with
the new UI and see any differences in behavior to understand what you might need to change to migrate
an application to the new UI.
As mentioned previously, when you use Rollbase links to access the documentation, the documentation set
appropriate for your UI will open. You can also access a specific documentation set in the following ways:
• By direct link:
• New UI documentation: http://documentation.progress.com/output/rb/doc
• Classic UI documentation: http://documentation.progress.com/output/rb-classic/
• When in the classic UI documentation, click the link under the printer, View documentation for the new
Rollbase UI
New properties in the shared.properties file

In Rollbase Private Cloud, the shared.properties file has been updated with the following properties:
• ProgressDataServiceCORSHost: Specifies the online address of the Progress Telerik host. This enables
Telerik applications to access Rollbase services.
• AllowMultipleRestSessions: Enables multiple REST API sessions per user. That is, Rollbase can
create multiple concurrent sessions for the same user and process REST API calls from all the sessions.
• MarketplaceURL: Specifies Rollbase Marketplace's relative URL that leads to its home page.
For more information about the above properties, see shared.properties on page 926.

Upgrading Private Cloud to Version 4.X
Documentation update for custom trigger development

Rollbase Private Cloud users can develop custom triggers. Prior to Rollbase 4.0, you used the samples and
documentation provided in custom development toolkit to develop a custom trigger. Starting with Rollbase 4.0,
you can use the Rollbase documentation to understand the customer trigger development concepts and
processes.
For information about working with custom triggers, see Working with custom triggers on page 388.

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:
• 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

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.


3
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.

Chapter 3: Designing a Rollbase application

Application foundation
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:
• Application foundation
• Business logic and customizing the user experience
• Setting up accounts for testing
• Distribution options
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 714
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.
• 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.

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 381 for more information.
• 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 712.
• 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 748 for more information.
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 413 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
610 for more details.
• Approval — Objects with this attribute are subject to an approval process. See Approvals on page 423 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 480.
• 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 426.
• Multi-Currency — Objects with this attribute include support for converting money amounts to and from
different currencies. See Multi-currency support on page 477

Business logic and customizing the user experience
• 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.

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 349 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 489 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.

Component Description
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 719.
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 506 for details.
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 255 for more
information.
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 490 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 490 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 413 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
343 for information on making mass updates.
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.

Type Purpose
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 displays in a pop-up window and

allows users to select one or more records for a lookup
field. You can open a selector page when creating,
viewing, or editing a record, by clicking the lookup icon.
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 594
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.

New record page example

This example new record page from a corporate room reservation system has controls for adding related
furnishings.

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.

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.

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.

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".

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:

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
247 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 490 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 519.

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:

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 506 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 499 for details.

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.

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 511.
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.

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 711 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 262 for details.

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 262 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 243 for more information about the Event, Task, and Workflow attributes.

• 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:

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:

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.

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 724 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 internet resources 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. Or, 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 on the Rollbase Application Directory or Marketplace. For more information,
see Publishing to the Rollbase Application Directory on page 785 and Using the Progress Rollbase Marketplace
on page 766.
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 779.
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.

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 594.


4
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 270 and Editing applications on page 274 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 273, and edit it to add the objects, as described in Editing applications on
page 274.
• 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 659
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

Chapter 4: Laying the foundation
The topics in this section describe how to create and manage applications and objects.
• 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:

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 243 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 1339.
• 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.

Creating and managing applications
• 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.

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.

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 771.
• Install from App Library — Opens the Rollbase Application Directory window, which displays a list
of applications you can install.
This option is available only for Rollbase Private Cloud users who upgraded from a prior version to 4.0
and Application Directoryhas been enabled in their tenant.
• 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:
1. From the application switcher:
• To navigate to settings for the current application, click Current App Settings.
• To navigate to settings for a different application, hover your mouse pointer over the application and
click the 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 290 for more information.
• Click the More actions... drop-down menu to perform advanced operations. See Application actions on
page 278 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 286 for more information.
• Click Post Install Scripts to add one or more post install scripts to the application. See Post install
scripts on page 296 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 525 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.
• 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 557 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 for the application.
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.
• Hosts Whitelist for Client REST API - Enter the name of hosts you want to authorize for client
side REST API calls and click Add.
• 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 427 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:
• 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:
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.
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.


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:

See Publishing and distributing applications on page 765 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 293.
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:

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 1150 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.

See Customizing the header and footer on page 518 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 621 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 372.
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.
For more information about string tokens, see Creating and using string tokens on page 359.
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.

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 719.
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 286 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 288
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 288).

To apply a theme to an application using the Theme Preview mode:
• 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.

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:

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.

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 286
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
Installing an application from the Marketplace

Users with a role of Administrator can log into their Rollbase account to install Rollbase applications from the
Marketplace.

The following procedure describes how to navigate to and install an application:
1. Open the 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 926.
• 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 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 Application Directory

Starting with Rollbase 4.0:
• In Rollbase Hosted Cloud, Marketplace replaces the Application Directory.

• If Rollbase Private Cloud is upgraded to Rollbase 4.0 from prior version, Application Directory continues
to be the platform to publish and distribute applications. However, master tenant administrators can enable
Marketplace and provide it to their customer tenants as an alternative of Application Directory.
For more information about publishing and distributing applications using Marketplace, see Using the Progress
Rollbase Marketplace on page 766.

In Rollbase Private Cloud, if you are using Application Directory for publishing and distributing applications,
you can follow the steps below to install an application published to the Rollbase hosted or Private Cloud
Application Directory:
1. Click Install Applications.
2. Browse the list of available applications to find the application you want to install.
3. Either click the application name or click More Details to see 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.
5. Click Install Now.
After finishing the installation, you can start using the newly installed application.
Updating an Application
To check for updates to an installed application:
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 987 for more information.
Overriding Changes
When installing updates from the Application Directory, 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
• 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 861 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.

Creating and managing objects, fields, and relationships
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.

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:

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
299 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:

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:

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. Click the page menu:
2. Select Object Definition from the menu.
• Navigate to the list of all objects:

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:

• 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 872
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 1339 for information about properties specific to
each type of field.

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.

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 page on page 793
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 page on page 793 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 page on page 793 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:

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.

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.

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.

• 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.
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 724.
See Setting field-level permissions on page 737 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.";
}
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 580.
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 497
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.

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 561 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:

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 575 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.

• 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 346 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
334.
• Merge allows you to merge the selected records. See Comparing and merging records on page 334.
• Convert allows you to convert the records to a different type. See Converting records on page 329.
• Find Duplicates allows you to find duplicates. See Finding and merging duplicates on page 337.
• Transfer Owners allows you to transfer owners. See Transferring owners on page 343
• Workflow actions, displays for objects with workflow enabled. See Workflow actions on page 415.
• Mass Update allows you to perform the same change to multiple records. Updating multiple records on
page 343
• 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:

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 menu:

2. Select Object Definition.

The object definition opens. A ribbon of components displays at the top of the page:
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.
The page editor opens.

3. Click the menu to the right of the view component to open its Properties menu:

Relationships between objects
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.

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.

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
• 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 338 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:

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:

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.

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:

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 1130.

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 497 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 312.
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.

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 511.

Working with records
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.

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 326

• Protecting records on page 328
• Converting records on page 329
• Finding and merging duplicates on page 337
• Auditing on page 338
• Sending email on page 340
• Transferring owners on page 343
• Updating multiple records on page 343

• Tagging records on page 346
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:

• 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:

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 719.
• Locking individual records as described in Locking records on page 328.
• Creating conditional formulas that remove edit and delete controls as described in Condition formulas to
disable editing and deleting records on page 328.
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 Unlock trigger type 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.

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 719).
• Rollbase applies the locking mechanism before a condition formula (see Locking records on page 328).
• 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 349 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.

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:

• 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:

5. Select the target object type. Available types include all deployed objects except the source object.
6. Click Next.
The Conversion Map screen opens:

7. Map the fields as desired. Required fields must be mapped. See Converting records on page 329 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.

Comparing and merging records

In a list view, the group actions menu offers options for merging, finding duplicates, and comparing records:

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.
• 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.

• 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:

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.
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 Traill 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.
For private cloud administrators, some types of administrative audit trail entries related to a customer tenant
can be found on the bottom of the Administration Setup page. These records include, for example, a copy
of email messages sent as result of large asynchronous data imports.
Audit trail records cannot be modified or deleted manually. Rollbase deletes them if the record they are associated
with is deleted. In this case, the audit entry will be in the associated user's audit trail.
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. This attribute applies even if the
object does not have the audit trail enabled.
• 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 menu:
2. Select Object Definition.

The object definition opens.
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:
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 791.
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 349.
• 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
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 365 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.
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.
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:

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:
1. Navigate to the Pages section of the object definition.

2. Locate the Mass Update page.
3. Click Clone.
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 sound system in their
Device field.
5. Click Save.
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.

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:

3. Enter the tags separated by commas and click Save.

5
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

Chapter 5: 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
• Working with templates
• Formulas
• Triggers and workflows
• 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.

See the following topics:
• HTML and Script components on page 351

• Adding template fields and integration links to an object on page 354
• Creating a record name template on page 364
• Creating and using string tokens on page 359
• Template token syntax on page 354
• Iterating through records on page 362
• Using EVAL blocks on page 364
• Email templates on page 365
• Document templates on page 366
• Communication logs on page 371
• Localization on page 372
• New record template on page 372
• Right to left support in templates on page 372
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 349 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 359 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:

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);
});

</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 821 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 349 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.

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

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 800)

• 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

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:

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 985
{!#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.

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.
{!#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.

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 349 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 815 for information about support for multiple languages. See Creating and using multilingual
string tokens on page 825 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:

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:

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

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>

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.

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.

3. Locate the Record Name Template property.

4. From the Template Helper, select one or more merge tokens and paste them into the Record Name
Template field. Add separator characters as desired.
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 1350.
• Send Email workflow actions, see Workflow actions on page 415
• Workflow triggers, see Trigger overview on page 381
Note: Only users with access to the Templates menu can manage mail and other templates. See The Private
attribute on page 741.
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:

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 301).
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.
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 372 for details.
Rollbase supports the following document formats for templates:
• Microsoft Word (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 1349 for more information.
• Template Document workflow actions; see Workflow actions on page 415 for more information.
• Workflow Triggers; see Change Workflow Status on page 393 for more information.
• Template-based Reports; see Working with reports on page 448 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:
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 835).
From the list of templates, click Map Form Fields (available only for PDF document templates) to bring up the
mapping page.
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.
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 366.
Where appropriate, use tokens as described in Template token syntax on page 354, loops as described in
Iterating through records on page 362, and JavaScript expressions as described in Using EVAL blocks on
page 364.
2. Open the Object definition (See Viewing and editing an object definition on page 301) 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 452).
• 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.
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 317.
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 programatically.
• Incoming gmail messages can be converted into communication log (see Incoming Gmail on page 709).
Localization
Rollbase provides full support for localization, including various date formats, currency formats, and multi-lingual
support. See My Localization Settings page on page 793 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.
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 413.
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

Formulas
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 page on page 792.
• When creating a mail template, select HTML as the format. See Email templates on page 365 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.
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
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:
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:

Formulas
• 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.
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 378.

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
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 359 for more
information.

Formulas
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.
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 926.
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

#CALC_MIN.R8011457( expression MIN of expressions for Expression is mandatory and must

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 )

Formulas
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 990).
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

• 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")

Original Formula Parsed Results Comments

if ("{!country#code}" == "US") Correct You must always enclose string tokens in
If ("CA" == "US") quotes or make them a part of larger string.
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.
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 390).
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 1020 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 407

• Create Audit Trail Record on page 393
• Validate Record Data on page 409
• Unique Fields Combination on page 407
• Update Field Value on page 407
• Change Workflow Status on page 393
• Create New Record on page 393
• Attach Related Record on page 392
• Create Template Document on page 394
• Run Triggers on Related Records on page 396
• Object Script on page 396
• HTTP triggers on page 394 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 384 for more details.


The following topics provide guidance on using triggers and the general steps for creating them:
• Trigger rules and restrictions on page 384

• Trigger timing options on page 384
• Best practices for trigger formulas on page 385
• Delayed and repeating triggers on page 386
• Creating a trigger on page 387
• Example: Set field based on a workflow status change on page 409
• Debugging complex triggers on page 411
• Debugging delayed triggers on page 413
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 411 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

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:

• 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 724.
• 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.

• 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 413 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 409, 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 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.
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
• 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 385 for more information.
• Trigger Delay Time — Optionally, set a delay time. See Delayed and repeating triggers on page 386 for
details.
• Recursion — Optionally, set times for the trigger to repeat. See Delayed and repeating triggers on page
386 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 develop custom triggers.

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 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 events.xml file that describes the trigger.
• Language translations of the trigger’s name and description in the lang_xx.properties 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).
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 390.
Custom authentication for Private Cloud

Private Cloud customers can develop and deploy a custom authenticator as an alternative to authentication
methods provided by Rollbase.
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.

Adding the Custom Authenticator to configuration files

To make Rollbase aware of the authentication option:
1. Add CustomAuthClass to your shared.properties file with the name of the custom authenticator
class. For example: CustomAuthClass=auth.CustomAuth.
2. Restart Tomcat to apply the changes.
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.
Developing a custom trigger

The section describes how to develop a custom trigger from scratch. Progress recommends that you understand
the implementation and configuration required for a trigger (Working with custom triggers on page 388) and
review the reference implementation in the custom development toolkit (Custom development toolkit for custom
triggers on page 389) before developing a custom trigger from scratch.
The high level steps for developing a custom trigger include:
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 information
• getVerifyJS(): Returns a JavaScript string that validates input data during the trigger’s configuration
• 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. Put trigger logic inside this method
To perform the trigger-specific action, a runtime class can use the TriggerRunner instance passed as a
parameter to get necessary run-time information, including:
• getCustomer(): Returns the current trigger instance representing customer tenant

• getHttpRequest(): Returns an HTTP request for UI-driven triggers
• getSharedValue(): Returns the value set by previous triggers
• getTransaction(): Returns the current database transaction. This 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: Do not create, commit, or rollback transactions in your custom trigger code as it can
corrupt data.
Note: Custom Development Toolkit provides a sample run-time class, CustomTrigger.java, for your
reference.
4. When compiling your custom trigger code, include the following Rollbase JAR files in the CLASSPATH:
• rb_util.jar: Rollbase utilities file.

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
5. Modify events.xml configuration file 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 in events.xml:
<Event id="CustomTrigger" className="trigger.CustomTriggerConfig"/>
If you installed PAS, the default location of events.xml is Pas_Instance\rollbase\config.

6. 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.
7. Build a JAR file of your java project.
Note: The Custom Development Toolkit provides a build.xml file that you can use to build a 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: For master zone only

• prod1: For all customer zones
• workflow: For delayed events of all customer zones
• search: For search calls of all customer zones
• webapi: For SOAP calls of all customer zones
• rest: For REST calls of all customer zones
• storage: For spreadsheet imports of all customer zones
10. Restart your Web server for the changes to take effect.
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 387).
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 407 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 427 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.
Create New Record

This trigger creates a new record from the current record using a conversion map. See Converting records on
page 329 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 407 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 366 for information about document
templates. See Document Template Field on page 1349 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 1346 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 365 for information about email templates.
You can create a Document Template Field on page 1349 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 1046):
Name Value Example
ReturnStatus HTTP Status rbv_api.getSharedValue("ReturnStatus")
ReturnBody HTTP Body rbv_api.getSharedValue("ReturnBody")
For example:
1. Create an HTTP GET or HTTP POST trigger.
2. Create an Object Script on page 396 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:
• 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.
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:
• 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 395.
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:
• 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
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 989 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 411 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:

Note: If this trigger is used, Progress highly recommends using the trigger debugger to ensure expected
results. See Debugging complex triggers on page 411.
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 387 for more information.
The high-level steps to configure a REST Service trigger include:
1. Provide a base path URL of the Rest Service, to which you want to connect, in the REST Service URL
field.
2. Select the required Http Method. Currently, Rollbase supports GET, POST, and PUT and the default option
is GET.
3. 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.
4. Click Configure to configure the Services and Mapping. The Configure REST Service page opens.
5. Optionally customize functions in the trigger formula.
6. 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 433 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.
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.
Configuring Query Parameters

The Request tab allows you 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 403 for more information.
GET Request: This is used to get details from the REST endpoint by mapping the Rollbase fields as new
mapping pairs.
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.
• 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 401 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
• 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

Related Array 1:M or M:M Uses all objects Create,Update, or Yes

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.
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 what each can 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 simpleJSON object which 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.
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.

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.

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:

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 365 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:

• 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 393 and Create New Record on page 393 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 393 and Create New Record on page 393 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 411 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

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 310).
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

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:

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
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 427, a fourth section, Debug,
is also included. This section displays the Corticon Server URL, the decision service request data, and the
decision service response.

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);
}
}

Debugging delayed triggers

Debugging delayed triggers is challenging because there is no one around when they run. See Delayed and
repeating triggers on page 386 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 411 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 724.
4. Progress recommends using Create Audit Trail Record on page 393 triggers for debugging purposes, because
the regular debug window is not available for delayed triggers.
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.
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.

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.
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.
When you configure a workflow status, you specify which workflow actions are available for records with that
status. See Workflow status on page 414 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 724.

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:

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.
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 515 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 724 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:

record view page
• 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 329.
• Use Record Template — A record template to create a new record (ignored if a conversion map is selected)

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:

record view page
• 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.
• 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.
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.

• 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.
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.

record view page
• 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.
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.

Creating a workflow process

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 407 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 301).
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 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 422 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 301).
2. From the ribbon, select Workflow Processes to navigate to the Workflow Processes area.
3. Click the name of the workflow process to view it.
The workflow process view screen opens:

4. 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 statues included in the process.
• Click New Workflow Status to create a new workflow status for the process.
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 423
2. Create an email template on page 424
3. Select approvers on page 424
4. Set the Approval attribute on page 424
5. Set up the Approval process on page 424
6. Optionally, customize the approvals process on page 424
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 365 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 490 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
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 424.
• 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.
• After reviewing a record submitted for approval, the approver clicks Approve Or Reject, which opens the
approval page:

• 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:

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.

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.

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 430 and Supported relationships for response mapping
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

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 430

• Supported relationships for response mapping on page 431
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.

See the following topics for more information:

• Supported data types and conversions on page 433
• Creating a Corticon Decision Service Trigger on page 436
• Overriding functions to provide custom behavior on page 441
• Example trigger mapping to related objects on page 443
• Example trigger mapping where response creates a record on page 445
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)

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 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

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 434

• Data type conversions on page 434
• Supported Date and Date/Time formats on page 434

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 434)
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'){

//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 441 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

• 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 437 for details.
2. Create the trigger as described in Creating a trigger on page 387, 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 433

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 443 illustrates request mapping from multiple Rollbase
objects.
• Example trigger mapping where response creates a record on page 445 illustrates response mapping that
creates new Rollbase records.

Configuring Rollbase to access Corticon Server

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.
• 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.
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 437 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.
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 433 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.
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 437 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.
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 433 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.
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 433 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.
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.
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:
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.

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.
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:

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 470 for details.
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 926 for more information.

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:
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
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 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 tabular report names reflected when you send report emails, create new batch jobs,
use report filters, and use report tokens in Document template.
5. 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.
6. Click Save.
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.

To create a document template report, do the following:

1. Create a new report by doing any of the following:
• Open an object definition, click Reports in the ribbon and click New Report.
2. Select an object to Report On and then select Document Template as your Report Type.
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 366).
6. Select one of the supported report file formats:
• Microsoft Word (DOC and DOCX)

• Microsoft Excel (XLS and XLSX)
• HTML
• RTF
• 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 724).
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.

To create an HTML template report, do the following:

• Open an object definition, select Reports from the ribbon, and click New Report.
2. Select an object to Report On and the select HTML Template as the Report Type.
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
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.

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
• 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.

To create a JavaScript based report, do the following:

• Open an object definition, select Reports from the ribbon, and click New Report.
2. Select an object to Report On and the select JavaScript as your Report Type.
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 1051 or rbv_api.println() on page
1052 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


8. Click Save.
Creating custom reports

A custom report lets you build a report with multiple sections of various types. See Section types for the available
section types. You use the Report Builder to create sections for the report. You can use custom reports to
build rich, highly customized documents to present your application's data. You can think of a custom report
as an aggregation of multiple individual reports in a book format.
You can design a report to run on a single record. For example, you could create a report that includes all
activity for a particular customer. You can design a report with sections that loop over groups of records. For
example, you could create a product catalog that loops over product categories and reports on information
about each product grouped by category. These are only two examples of the many ways you can organize a
report. Custom reports are flexible and they allow you to design a report that meets your requirements.
To create a custom report:
1. From an object definition, click Reports in the ribbon.
2. Click New Report.
3. Select the Custom report type:
4. Click Next. The Report Properties page opens. Custom report properties include:
• The name of the report

• An optional description
• Whether to render the report as a PDF. Reports rendered as PDF can include an automatically generated
table of contents. See PDF report options for custom reports on page 456 for more information.
• 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 custom report names reflected when you send report emails, create new batch
jobs, use report filters, and use report tokens in Document template.
• An optional CSS stylesheet. You can type custom CSS styles in the text area and/or reference a hosted
CSS stylesheet. For example, you might use the same hosted CSS files for all of your custom reports,
but you can use the text area to add additional customizations that only apply to a particular report. See

Hosted files on page 617 for more information about hosted files. See Custom CSS on page 581 for more
information about custom CSS.
• Role and user based permissions for the report. See Access control on page 724 for more information
about setting permissions.
5. Click Save & Continue to Report Builder to add content to the report. See the following topics for more
information:
• Using the Report Builder on page 457

• Editing the report header and footer on page 457
• Adding sections to a custom report on page 459
PDF report options for custom reports

When creating or editing a custom report, you can specify that the report will be rendered as a PDF document.
Only reports rendered as PDF documents can contain a table of contents. See Table of Contents section on
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 Creating custom reports on page 455), select Custom, and click Next.
• Open an existing custom report.
The Report Properties page opens.
2. Click the Render as PDF check box. The PDF Options section appears with the following options:
• 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.
• Margins (mm) — Specifies the space (in mm) to be left for page margins. The default margin size is 20
mm.
• Pages to skip (Header) — Allows for a certain number of initial pages to not have a header. This is
useful where 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 for a certain number of initial pages to not have a footer. This is useful
where 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, 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.
• Landscape orientation — When selected, specifies that your PDF report be generated in landscape
orientation. Clear the check box to print in portrait orientation.
When you run the report, it will be rendered as a PDF document with the specified properties.

Using the Report Builder

A custom report includes the following parts:
• Header — Header content that appears at the top of each report page
• Footer — Footer content that appears at the bottom of each report page
• Sections — Report content. Sections can contain sub-sections. Sections and sub-sections create a
hierarchical tree structure for a report.
You can use the Report Builder to create and organize report sections, to edit the header and footer that will
appear on each page of the report, and to save and preview the report. The Report Builder is only available
for custom reports. Open the Report Builder from the Report Properties page by clicking Save & Continue
to Report Builder. The screen below shows the Report Builder for a newly created report before any sections
have been added:
At any time while building a report using the Report Builder, you can:
• Return to the Report Properties page by clicking < Report Properties.

• Save and generate a preview of the report by clicking Save & Preview.
• Save the report by clicking Save.
• Exit the Report Builder without saving the report by clicking Cancel.
To add a section to the report, click New Section. See Adding sections to a custom report on page 459 for more
information.
To edit the report's header or footer, click its edit button. See Editing the report header and footer on page 457
The following sections describe how to add content to a report.
Editing the report header and footer

A header contains content that appears at the top of every report page. You can use plain text, HTML, and
custom report tokens in the header content. 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 example,
if you want the report's header to contain the name of the report, you can insert the Page Title token.

To edit the report header or footer, click its edit button:
A rich HTML editor opens. Add the content you want to appear at the top of each report page and format it as
desired.
Click the button in the upper right to generate a token you can use in the header or footer content.
The following screen shows the different tokens you can generate:
The following screen shows the Page Number token in the report footer:

See Using tokens in custom reports on page 465 for more information about tokens.
Adding sections to a custom report

When you add a section to a report, the new section is added to the left pane. This pane shows the hierarchical
structure of the report. You can organize sections in the report by dragging them to the desired locations in
this pane. You can close and reopen this pane, either by clicking the arrow in its right margin or by clicking the
rightmost button at the top of the screen.
Sections can have sub-sections. A sub-section is a child section. Sub-sections can also have sub-sections.
You can add the following types of sections to a custom report:
• Plain Text & HTML — Section content is plain text and HTML. See Plain Text & HTML section on page 461
for details.
• HTML Template — Like an HTML Template report, allows you to define an HTML template for the section
content. See HTML Template section on page 462 for details.
• Sub-Report — Allows you to select an existing report for the selected Source Object as the content of the
section. See Sub-Report section on page 463 for details.
• Loop — Executes a loop on Source Object records, taking into account the sorting and filtering criteria
you specify. For each record, sub-sections of the loop are evaluated. See Loop section on page 464 for
details.
• Table of Contents — A placeholder section for a table of contents for the report. When generating the
report, entries for sections with the property Show in TOC checked are added to the table of contents
section. A Table of Contents section is only generated for reports rendered as PDF documents. See Table
of Contents section on page 465 for details.
To add a section to a report, click New Section in the Report Builder. The following screen opens:

Set the following properties for a section:
• Section Identifier — An identifier for the section that appears in the report structure in the left pane.
• Section Title — A title for the section. 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.
• Section Type — The type of content in the section. See Section types for the available section types.
• Source Object — The object on which to base this section. It can be the same object as the report is based
on or it can be another object in the application. The selected object does not need to have a direct
relationship with the object on which the report is based.
• Show in TOC — When selected, the Section Title appears in the TOC.
• Info-Section — When selected, the Section Title is rendered as a header in the section.
• Add Page Break — When selected, the section will start on a new page in the generated report.
Different section types support different ways of adding content. See the following topics for details about each
section type.
At any time, you can click the hashtag button at the upper right to open the token generator to generate a token
for use in the section's content. See Using tokens in custom reports on page 465 for more information.
When creating or editing a section, you can perform the following tasks:
• Click Add Sub-Section to add a sub-section to this section. You can add any number of sub-sections to a
section.
• Click Clone to create a new section that is identical to this section.
• Click Delete to delete this section.

Plain Text & HTML section

When you select Plain Text & HTML as the section type, the Report Builder displays a rich HTML editor
where you can enter the content of the section:
You can use tokens in the editor; tokens are resolved when the report is generated. For more information about
tokens, see Using tokens in custom reports on page 465

Wizard section
When you select Wizard as the section type, the Report Builder displays a user interface that lets you select
fields, sorting and grouping, totals and subtotals, and report filters for the section. The interface is similar to
the one you use to create tabular reports except that you can only create one layer.
HTML Template section

When you select HTML Template as the section type, the Report Builder displays an HTML Template Details
section that includes Template Helper where you can build an HTML template for the section:

It also displays a Report Filters section where you can define filter conditions for the section:
Sub-Report section
When you select Sub-Report as the section type, the Report Builder displays a drop-down menu where you
can select an existing report. The content of the selected report will be the content of the section. Only reports
defined for the Source Object are available.

Loop section
A Loop section does not contain any content. Instead, it defines a loop over a list of records of the selected
Source Object. Report content is generated by sub-sections of a Loop section. A Loop section's sub-sections
are executed on each of those records in the order you specify in the Loop section. You can apply standard
filtering criteria to execute sub-sections on a subset of records. See Filter criteria on page 567 for more information.
When you select Loop as the section type, the Report Builder displays sorting and filtering criteria you can
apply to the records. For example, if the report is defined on the Room object, and the Loop section's Source
Object is Furniture, you can filter the Furniture records to include only those in the specified room. You can
use the Context Record token to access the Room record in the filter criteria. In the sub-sections of the Loop
section, you can use the Loop Record token, which resolves to the current Furniture record in this example,
as well as the Context Record token. For more information about tokens, see Using tokens in custom reports
on page 465.

Table of Contents section

Custom reports do not have a table of contents unless you add a Table of Contents section, which you can
add 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. Only sections with the Show in TOC property checked appear in the Table of
Contents section.
Note: Rollbase only generates a table of contents for reports rendered as PDF documents.
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 clicking the pound sign button in
the upper-right corer of the report builder. This opens a dialog where you can select from the available tokens;
each type of token is represented by a tab. 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:

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
Page Number The page number of the report Headers and footers
Count of total The number of pages in the report Headers and footers
pages
The following screen shows the token generated for the Loop Record's Description field:
The following screen shows tokens used in a section header:

The following screen shows the resulting header in a report preview:
Note: When a report section uses the Context Record token, Rollbase cannot resolve the token when you
Save & Preview the report. See Viewing custom reports on page 467 for information about how to view a report
that uses this token.
Viewing custom reports

The Report Builder includes a Save & Preview button that opens the report in a preview window. For reports
that are not designed to run on a single record, you can use this to preview a report as you develop it. For
reports that are designed to run on a single record and use the Context Record token, you cannot use this
feature because the preview requires a specific record as the context for running the report.
To enable viewing a custom report designed to run on a single record, you need to access the report from an
application page where you can run the report. 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.

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 that 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 724.
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.
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 497 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:
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 811.
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 stylings for custom reports in two general ways:
• 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 Creating
custom reports on page 455 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>
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:

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 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.

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.

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 865 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.

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

Multi-currency support
also use the Rollbase Query API in gauges. For more information about formulas, see Formulas on page
373.
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 373.
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:

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 478
2. Set up exchange rate on page 479
3. Enabling multi-currency attribute on the object definition on page 479
4. Money amounts in base currency on page 480
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

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 1285). 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.

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:

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 482. 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 486 and Adding questions to a
survey on page 484.
4. Distribute the survey link in one of the ways described in Survey pages and links on page 486.
5. See how survey takers responded as described in Collecting survey answers on page 488.

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 menu, select Object Definition:
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 settings
icon.

Surveys and quizzes
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:

d) Click New Menu.

The New Menu page opens:
e) For Menu Name, enter Questions.

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.

Surveys and quizzes
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.
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.
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.

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 611.
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 598.
6. Create a portal page of the type Take Survey. See Creating portal pages on page 598.
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).

6
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.
• Pages, the page editor, and grid controls
• UI blueprints
• Live Preview
• Adaptive user interface
• Responsive user interface
• Working with views
• Working with themes
• Programmatic client-side customization
• Rollbase portals
• Hosted files

Chapter 6: Customizing the user experience
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 247 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:
• 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:

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 255 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.

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 724 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 495 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:

The object's pages are displayed in a table:

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 584 for the page (not available for Selector pages). The screen below shows
the Page Properties page for an Edit page:

• 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:

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):
When Fluid is selected, the page is not responsive to different screen sizes.
See Editing pages on page 497 for information about the page editor.
Click Properties to view and edit page properties.

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 32 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 258 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:

• 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 492 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 495 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.

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 258 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:

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:


Other components you can add to a page include:
• Lookup fields — Allow users to select a related record. See Relationships between objects on page 317 for
information about configuring lookup fields.
• Charts — Allow you to visually display a snapshot of data. See Using charts on page 474 for information
about configuring charts on a page..
• Gauges — Allow you to visually display a single value. See Using gauges on page 477 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 353 for details.
• Script components — Allow you to add JavaScript formulas to a page. See Adding a script component to
a page on page 353 for details.
• Detailed search components — Allow you to filter records by a set of preconfigured fields and operands.
See Detailed search on page 502 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 504 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 323 for more information.
• Page tabs — Allow you to organize page sections into different visible sets for complex pages. See Page
tabs on page 506 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 511 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.

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)

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.

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.

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:

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:

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 510 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:

The screen below shows the page editor open on the same page with the View System Info tab selected:

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.

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 724 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 317 for more information about lookup fields.

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 1099 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 512

• Configuring a grid control on page 513
• Using a grid control on page 515
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 498 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 513

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.
4. From the list of available columns and formula fields, select the fields you want to appear as grid columns
and use the arrows to move them to the Selected Columns list.
Although you can use most field types in a grid component, there are some limitations. For example, you
cannot use filtered lookup fields.
5. Optionally reorder the columns using the up and down arrows.
6. Click Next.
The last page of the wizard opens:

7. On this page, choose from the following options:
• Check Required in Grid for fields you want users to enter a value.
• Check Read Only for fields that users should not be updated on this page. This has no effect on required
columns.
• Optionally specify sorting for columns.
• Configure lookup fields for related records:
• Choose Selector or Picklist from the first drop-down menu.
• Select Enable Quick Create if you want to be able to create a related record using Quick Create.
• Select the list view to use 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 1099.
8. Click Save.

Using a grid control

As shown in the following screen, grid controls provide controls for adding, deleting, and editing records:
The following controls for creating, deleting and editing are available to users with the appropriate permissions:
• To add a new related record, click + next to the grid heading.

• To delete a record, click Delete.
• To modify a field, click in the field and enter the new data.
• To configure the grid, select the Configure Grid icon.
Rollbase saves changes to each related record in the grid when you save the page. If an error occurs in one
of the rows, Rollbase displays one or more error messages below the grid component.
After a successful save, a message in the page header describes how many line items were created, updated
or deleted.
This topic described basic grid functionality. You can add logic as described in Grid Control Examples and API
on page 1099.
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.
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 350
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.

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, as shown in the
following screen:
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 617 for details.
You can use the same techniques to customize the sidebar for an application (see Custom sidebar on page
283) 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 350, Formulas on page
373, and Client-side JavaScript on page 1150 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;
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;
padding: 10px;
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',
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 255 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
You can promote a child menu to be a tab by removing its parent tab. See Promoting a child menu to a tab on
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 523
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. This procedure uses the Library
Members tab in a Library application as an example:
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. In
this example, the Manage Users tab is selected as the parent tab:

5. Click Save.
The tab is now a child menu of the Manage Users tab in the application menu bar:
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:
• To navigate to settings for the current application, click Current 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. To edit a child menu, you must edit its parent tab. This procedure uses the Library
Members child menu under the Manage Users menu item in a Library application as an example, so the
tab to edit is Manage Users:

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.
The child menu is now a tab in the application menu bar:

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:
rb.newui.options.numOfCharsInTabDefaultIcon=2;
</script>
The following screen shows the resulting icons in a collapsed sidebar:
To configure an individual tab to use a font icon:

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:
To configure an individual tab to use a custom image as its icon:

2. Select Custom as the Icon Type and select the file to use as the menu icon:

UI blueprints
The following screen shows a collapsed sidebar where the Devices tab uses a custom icon:
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.

UI blueprints
The following screen shows the Modern - Vertical Menus blueprint with the application switcher selected.
The following screens show the Modern - Vertical Menus blueprint on a desktop in its two states. Open the
sidebar by clicking the hamburger menu at the top left of the screen. Expand or collapse the sidebar by clicking
the hamburger menu.


UI blueprints
The following screen shows the Modern - Vertical Menus blueprint on a smart phone.

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, select the UI blueprint from the UI Blueprint drop-down menu:

Live Preview
4. Click Save.
You can also set the UI blueprint for an application using Live Preview on page 531.
The UI blueprint for each application appears in the application list on the applications setup page:
Live Preview
Live Preview is a tool where you, as 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.
To open Live Preview, do one of the following:
• If you are using the Traditional blueprint, click Live Preview from the Rollbase menu:

• If you are using the Modern - Vertical Menus blueprint, expand Administration in the sidebar and click
Live Preview:

Live Preview
Live Preview lets you select options for the following:
• 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 525 for more information.
• The theme for the application. See Working with themes on page 578 for more information about themes.
• The field label setting. This specifies whether to place field labels to the left of field values or above field
values based on the device. See Customizing field labels on page 553 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 538 for more information about cards.
• Toggle the text direction. See Language support on page 815 for more information about language support
and text direction.
Click the save icon to save your changes or click the X icon to discard your changes and close Live Preview.
The following screen shows the Live Preview interface. In this example, the user has selected the smart phone
interface, selected a different theme, and selected a user-defined card:

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 535.

Adaptive features include:
• Rollbase renders record list pages on mobile devices using cards and card containers. See Cards and card
containers on page 538 for information about cards and card containers. See Creating and editing cards on
page 539 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 551 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 553 for more information.
• Rollbase includes client-side JavaScript functions for detecting mobile devices. See Functions on page 1158
for details.
• Rollbase includes CSS classes for detecting mobile devices. See Custom CSS on page 581 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:

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.

• 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 538 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.
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:
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 539 for details.
Creating and editing cards

The card editor allows you to create and edit cards for displaying in card containers on various devices.
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:
1. Decide which object type for which you want to create the card and open a record list page for that object
type.
2. Open Live 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.

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.

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 543. 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 544
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.

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 543
• Editing a card in the card editor on page 544
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 544

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 544
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.

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:

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.

• 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.

• 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:

• 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:

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.

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.
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:

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:

The Show In property is displayed in the table of buttons in the object definition. See Using buttons on pages
on page 515 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:

The following screen shows an application page with labels above field values on a smart phone:
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.

Responsive user interface
To hide a field label, open the View page in the page editor and select the Hide Label property for the field:

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.

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 557 for details.
• Responsive dashboard pages. See Responsive dashboard pages on page 560 for details.
• Responsive page title and toolbar. See Responsive page title and toolbar on page 559 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.

• 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
1347.
• 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 471 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 274 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:

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.

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

• On small devices (width is 768px or less), the page title consumes 30% of the width and the toolbar consumes
70% of the width.
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:

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>
width: 20%; /* Rest of space will be consumed by toolbar buttons and overflow */
}
}
width: 20%; /* Rest of space will be consumed by toolbar buttons and overflow */
}
}
</style>
Responsive dashboard pages

Rollbase supports responsive generic pages (pages you create from generic tabs; see Creating tabs and pages
on page 490) 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:
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.

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 865
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.

• 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.
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 563 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 565 for more information.
8. In the View Filters section, choose the fields and operation for filtering. See Filtering views on page 566 for
more information.
9. In the Permissions section, specify which roles and users can see this view. See Role-based access control
10. Click Save.
You can also edit a view on an application page. See Editing a view on an application page on page 572 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 308 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:

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:

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 578 for more information.

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.

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.

Working with views
See the following topics for details:
• Filtering by date intervals on page 567

• Filter criteria on page 567
• Filtering by formula on page 569
• Filtering OpenEdge Service objects by search criteria on page 570
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.

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 569.
• 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 570.
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.

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:

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 665.
The search criteria supports the following search conditions:
• String
• Numeric
• Logical
• Date

Working with views
The following table provides search examples:
Table 2: 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

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.
• Inline editing on page 572

• Dynamic filtering on page 575
• Color coding rows on page 577
• Column data options on page 578
Inline editing
Records in a view can be edited inline just like fields on view record pages.

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.


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 567.
For information about formula filters, see Filtering by formula on page 569.
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.

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 1163 — Determines whether the control for advanced filter types is
displayed
• showBooleanOperators on page 1164 — Determines whether the control for Boolean operators is displayed

Working with views
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:
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:
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 page
The following screenshots show different built-in themes applied to an application:

Working with themes

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
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
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 1064. For detailed
descriptions of the Rollbase JavaScript APIs, see Client-side JavaScript on page 1150.
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 801 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.
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.
Changing the page title width

On view and edit pages, the page title area has two parts:
• The page title
• 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.
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:

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:

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.
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.
UI Blueprint options
Based on the selected UI template, object view title will change to red for Modern Vertical BP and green for
traditional.
.rbs-ui-template-type-2 .rbs-objectViewTitle { color: red; }
.rbs-ui-template-type-default .rbs-objectViewTitle { color: green; }
Changing the page title width

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>
*/
}
}
*/
}
}
</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:
.rbs-simpleField-label-cell { width: 40%; }
.rbs-simpleField-value-cell { width: 60%; }
.rbs-editField-valueContainer { width: 95%; } }
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.
See 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 location of the CSS files 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.
Rollbase includes FontAwesome icons, which are scalable vector icons that
chttps://demos.telerik.com/kendo-ui/themebuilder/an 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/
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.
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, onselect, onmouseover, onmouseout. A picklist
exposes the following: onchange, onclick, onfocus, onblur, onmouseover, onmouseout. Read-only
and hidden fields do not expose any handlers.
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.
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);
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 586, 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) {
if (membership_fee.value=='') {
var code = membership_type.options[
membership_type.selectedIndex].getAttribute('code');
if (code=='A')
membership_fee.value=1000;
else if (code=='C')
else
}
}
}
</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.
Using system settings to define values that might change

The example shown in Setting default values on page 587 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 587:

2. Click Settings under Administration Setup
3. Click Configure:

The object definition page for Settings opens.

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 304 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 1064 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.
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 497):
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:

A simple lookup
Consider the following example: A Rollbase page includes a lookup field (see Relationships between objects
on page 317) 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:

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:

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 497):
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>

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 719 for more information about access control and permissions.
See Client-side AJAX API on page 1064 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 765.
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 610 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.

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 607 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 611.
• 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 610.
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 610 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 613 for more
details about developing this portal.

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 613 and Creating portals with authentication on page 614
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 596
• Creating portal pages on page 598
• Creating a custom header and footer on page 607
• Portal security on page 610
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:

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.
• Use Bootstrap v3: If this box is checked, Rollbase will add Bootstrap 3-related CSS and JS files for the
portal. Note that when Bootstrap 3 is included, Bootstrap 2 is no longer included.

• 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 607 for more information.
7. Configure Portal security on page 610.
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.

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 610 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 605 for instructions. Portal
visitors must log in to the portal to take a survey.
• See Using surveys on portals on page 488 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.

The portal page editor opens:
Editing a portal page is similar to editing an application page. See Editing pages on page 497 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 353 for more
information.
• Drag a script component onto the page. See Adding a script component to a page on page 353 for more
information. The script component can be an EVAL block; see Adding an EVAL block to a portal page on
page 601 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
605 for details.

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 364 for more information about #EVAL[ ] blocks. See Server-side API on page 989 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.
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:

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:

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:

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

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 604 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.

• 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]:

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".

• 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:

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 349.
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.

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:

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 611 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 742 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 791.
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 926 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 614 for examples.
Creating a portal user

As described in Portal security on page 610, 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 298 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
497 for details about adding fields to a page.

3. Edit the object's Edit page to add the Login Name and Password fields to it. See Editing pages on page
497 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:

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:

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 605 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 599 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 599 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
611 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:

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
611 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:

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

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 724).
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 1331) 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 791.
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 619 and Using hosted file tokens on page 619for 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:



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 files
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.
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 989.

7
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
555 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 534 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.

Chapter 7: Supporting mobile users
• To use Progress Data Catalogs with the Telerik Platform, see Using the Telerik Platform to create a
mobile app on page 622
• 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 654 for details.
• 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 623 for more information
about creating a data catalog.
2. Identify the following values:

• 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 624.
• Use the sample Progress Data Service project as described in Creating a mobile app using Code and
the Progress Data Service template on page 645.
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.

• 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 624.
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 626.
3. Create and test the initial views (screens), as described in Create or configure an Authentication view on
page 630 and Create a Master Detail view on page 636.
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 641.
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 645.
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:

3. Enter an App name and an optional Description.

4. Click Create App.
The new project opens with the Views screen in focus:

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.
Next, Add a Progress Data Service provider on page 626 so that the app can connect to Rollbase.
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:

2. Click Add Provider and select Progress Data Service from the drop-down menu.
The Connect to a Progress Data Source dialog opens:

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:

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 630 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.

Next, Create or configure an Authentication view on page 630.
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 631. Otherwise, to create an Authentication view for a
Progress Data Service provider, start with Step 1 on page 630:
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:

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:

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 626 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):

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.

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:

To test the view, enter a valid Progress ID and password in the device simulator.
Next, create a Master Detail view.

Next, Create a Master Detail view on page 636.

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.
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 626 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:

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:

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:

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.
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.

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 637.
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.
Next, Configure navigation and extend the app with Code on page 641.

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 636. 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:

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:

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:

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:



If you reopen the app, custom code added elsewhere in the source files is likely to be lost.

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 645.
2. Specify the settings, as described in Configure JSDO settings on page 647.
3. Test your app and see the starter implementation, as described in Test the app on page 649.
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 624.
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.

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:

Next, configure JSDO settings so the app can connect to Rollbase.

Next, Configure JSDO settings on page 647 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:

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 on page 32 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:

Next, Test the app on page 649.
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. This example shows the iPhone 6 simulator.

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 on page 32 for more information.
4. Select the List page.

The values for field display. In this example, a list of book titles, authors, and publishers:

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.
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.
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.

Global Search
A global text search box at the top of every page in allows quick and easy searching through records for which
the user has access. Results are shown in a pageable list from which the user can drill down to view individual
records.
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.

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.


8
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.
• 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

Chapter 8: 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 1173, Rollbase REST Methods
on page 1216, and Rollbase SOAP Methods on page 1285.
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

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 676.
• 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

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 660.
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:
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. Select OpenEdge Service and click Next.

The Import Objects from OpenEdge Services page opens.
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 666 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 666 to learn
what a Data Service Catalog must include to fully use Rollbase functionality.
• 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 OpenEdge authentication details on page 886.
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:
• 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. 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.
If you are using Hosted Rollbase:
• 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 666 to learn what a Data Service
Catalog must include to fully use Rollbase functionality.
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 666 to learn what a Data Service
Catalog must include to fully use Rollbase functionality.
• 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 OpenEdge authentication details on page 886.
• 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.
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 ?
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:
------------------------------------------------------------------------------*/
@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.
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
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:
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):

iSeq = iSeq + 1
END.
/*------------------------------------------------------------------------------
Purpose: Create one or more new records
Notes:
------------------------------------------------------------------------------*/
@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:
------------------------------------------------------------------------------*/
@progress.service.resourceMapping(type="REST", operation="update", URI="", alias="",
METHOD PUBLIC VOID UpdateCustomer(INPUT-OUTPUT DATASET dsCustomer):
THIS-OBJECT:CommitCustomer(INPUT "", INPUT ROW-MODIFIED).
END METHOD.
/*------------------------------------------------------------------------------
Purpose: Delete a record
Notes:
------------------------------------------------------------------------------*/
@progress.service.resourceMapping(type="REST", operation="delete", URI="", alias="",
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:
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:
------------------------------------------------------------------------------*/
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:
------------------------------------------------------------------------------*/
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 */

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
ELSE
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
END.
iCount = 0.
REPEAT WHILE NOT hQuery:QUERY-OFF-END AND iCount < iMaxRows:
IF AVAILABLE Customer THEN
DO:
CREATE ttCustomer.
BUFFER-COPY Customer TO ttCustomer.
iSeq = iSeq + 1
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:
END FINALLY.
END METHOD.
METHOD PUBLIC VOID AddIdField (INPUT DATASET dsCustomer):

iSeq = iSeq + 1
END.
/*------------------------------------------------------------------------------
Purpose: Create one or more new records
Notes:
------------------------------------------------------------------------------*/
@progress.service.resourceMapping(type="REST", operation="create", URI="", alias="",
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:
------------------------------------------------------------------------------*/
@progress.service.resourceMapping(type="REST", operation="update", URI="", alias="",
METHOD PUBLIC VOID UpdateCustomer(INPUT-OUTPUT DATASET dsCustomer):

SUPER:UpdateData(DATASET-HANDLE hDataSet BY-REFERENCE).

END METHOD.
/*------------------------------------------------------------------------------
Purpose: Delete a record
Notes:
------------------------------------------------------------------------------*/
@progress.service.resourceMapping(type="REST", operation="delete", URI="", alias="",
METHOD PUBLIC VOID DeleteCustomer(INPUT-OUTPUT DATASET dsCustomer):


SUPER:DeleteData(DATASET-HANDLE hDataSet BY-REFERENCE).

END METHOD.
/*------------------------------------------------------------------------------
Purpose: Submit a record
Notes:
------------------------------------------------------------------------------*/
@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
570.
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 243.
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 662).
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:

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
Multi-Currency Currency Code CHARACTER
Rate Date DATE
Lockable Is Locked LOGICAL
Document Document File 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).

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 662), edit your object definition (see Viewing and editing
an object definition on page 301) 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.

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:
The What do you want to create? dialog opens:
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:
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.
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.

Calling Progress Corticon decision services from Rollbase
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.
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 427 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 681

• Creating objects from MDB tables on page 682
• Mapping fields and creating records on page 684
• Reviewing results on page 688
Uploading the MDB file

To upload an MDB file:

2. Click Create from External Data. The Import Application Metadata page opens.
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.
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 243 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 243 for more information about available attributes.
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.
• 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.


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:

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:

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:

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.

Creating a Rollbase application from a Salesforce application
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.
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.
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 678 or Creating Rollbase objects from OpenEdge Object Services on page 660.
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 845 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 868 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.
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 693.
• 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 695. For your convenience, the system will redirect you to the Adjust SQL page after a field is created or
deleted.
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.

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.

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 file, 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 file 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.

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.

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.

Importing data
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 703.
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).

• 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 704.
• 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 1216.
• 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 jobssimultaneously. See Component specific properties on page 918 for more
inofrmation.
• 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:

Importing data
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 699.
To import a spreadsheet or CSV file to create new records, update existing records, or delete records, follow
these steps:

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.

Importing data
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 242. 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 243)
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.

• 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.
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.

Deleting multiple records by importing a spreadsheet
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:
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

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 707.). 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;

Integrating with Google applications
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.

Rollbase provides an integration with Google applications as described in the following topics.

In this section:
• Enabling Google integration on page 708

• Incoming Gmail on page 709
• Outgoing Gmail on page 711
• Google spreadsheets on page 711
• Synchronizing with Google Calendar on page 711
• Google Maps on page 712
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 828
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 Third Party Settings page on page 793 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):

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 708), 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.

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.

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 708 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 708), 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 706 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.

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 708 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.

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.

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 programatically 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.

Using SOAP or REST to integrate with Rollbase
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 1285 and SOAP Metadata Methods on page 1190 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 1216 and REST Metadata Methods on page 1203 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

• 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 717)
• 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.

Integrating apps using Cloud Data 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.
• 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.
• 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.

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 Third Party Settings page on page 793 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= username@companyname.com
3. MailPassword=myPassword

9
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 720 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 724 for details. Rollbase Private
Cloud provides additional access control mechanisms. See Private Cloud security and access control on page
874 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 874 for security features unique to Rollbase
Private Cloud.
• 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

Chapter 9: Security and access control
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 with 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.
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 874.

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.

To configure a whitelist of IP addresses:

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

User authentication
You can limit whitelist control to a group of selected roles. If you want to apply the whitelist to all roles, do not
make any selection. To limit whitelist control 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 742, 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.
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.

Access control
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 740 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
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 Users No
Configure Support Access No

Permission Granted by default
View Integration Password Yes
Search Box 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.
• 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 add a new
role or edit an existing role as follows:


Access control
2. In the Administration Setup section, click Roles.

The list of currently defined roles opens:
3. Perform one of the following:
• To define a new role, click New Role.

• To change the properties of an existing role, click Edit.
• To copy an existing role and save as it a new role, click Clone.
• To edit the permissions of an existing role, click Permissions. See Setting permissions by role on page

• To assign a landing page for the role, click Pages. See Assigning a landing page to a role on page 733
• To view a role, click the role name.
The following screen shows the Edit Role page for a user-defined role:
4. The available fields include:
• A name for display purposes.

• An optional Integration Code. Specify a value to use this role in formulas and triggers.
• A description of the role.
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:


Access control
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.

5. Click Save. The user now has the selected role.
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:


Access control
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:

Object permissions and permissions for each object's views, reports, charts, and workflow actions:
Tab permissions and permissions for each tab's menus:

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:


2. Select Roles.
3. Select Pages next to the role to which you want to assign a landing page.

Access control
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 page on page 794.
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.
You can also set these permissions on a role's Permissions page as described in Setting permissions by role
on page 730. 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.

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:

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.

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:

• 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 989 for more information.

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 730 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.

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

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). The following graphic shows an example where the user Mike Sancilardi reports
to Joe Recruiter and Taras Bulba reports to Mike:
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)

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:

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:

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

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 752 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 756
for details about setting LDF values in records.

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.

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
Application Directory on page 291 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.

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).

Access control
When you create a group, you give it a name and assign values to any or all of the LDF fields:

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 497 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 497 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:

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:
2. Click Objects in the ribbon.

3. Click Edit next to the object to modify.

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.

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:

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:

User authentication and password management
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.

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 sucessfully 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 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 number of 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 activation/reset link is 2 hours. This can be configured by modifying the shared
property, PasswordActivationLinkExpiry, at system level or authentication configuration at a tenant level.

Enabling an administrative user to log into a customer tenant
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 1233 and
setAuthentication on page 1269 methods for more information.
Deprecated Tokens
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 862.
To enable a master tenant to log into a customer tenant:


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.
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.

Security for portals
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 shared property - 'EncryptionType'.
To make use of AES-256 on a Rollbase Private Cloud:
1. Set value of shared property ‘EncryptionType’ from 0 to 1. This is a one-time setting.
Once set to 1, reverting to 0 is not recommended. If no value is specified,
‘EncryptionType’ uses its default value, 0. No additional changes are required if you
want to continue using AES-128.
2. Install Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files 8 to
enable the 256-bit Key Size used by AES-256. For download and usage instructions, see
http://www.oracle.com/technetwork/java/javase/downloads/jce8-download-2133166.html.
Note: If these JCE files are not installed and the property ‘EncryptionType’ is set to 1, 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.
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 610.


10
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 720 and Role-based access control on
page 724.
2. To distribute to the Rollbase community for sale or free, publish an application on the Rollbase Marketplace
or Application Directory. See Using the Progress Rollbase Marketplace on page 766 and Publishing to the
Rollbase Application Directory on page 785.
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 779 and Generating application
XML on page 784.
Note: Only Rollbase Private Cloud administrators who have moved from earlier versions of Rollbase to
Rollbase 4.0 can enable Application Directory.
• Using the Progress Rollbase Marketplace
• Distributing applications in XML format
• Troubleshooting published applications

Chapter 10: 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 290 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 773 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 771.
The following diagram shows how users access the 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
926.
• Marketplace on Hosted Rollbase: https://www.rollbase.com/master/marketplace
The following screen shows the Marketplace home page:

Publishing an application to the Marketplace

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 (see
Submitting an application to the Marketplace on page 769). 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 and publishing an application
on the Marketplace on page 771)
Submitting an application to the Marketplace

Any user with a role of Administrator can submit an application to the Marketplace.
To submit an application to the Marketplace:

1. Navigate to application settings and click Publish.

The Publish Application dialog box opens.
2. Click Publish or Publish Updates.
The Publish Application dialog box opens.
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 782.
• 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.

• 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.
The application is submitted to be published on the Marketplace. You receive an email after your application
is approved on the Marketplace.
Additionally, using the Marketplace application, the administrators of the master tenant can directly publish an
application using its XML file. They have to use the New Published Application option on the Published
Apps menu.
Approving and publishing an application on 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 tenant administrators can review and choose whether to publish applications
submitted to the Marketplace for their Private Cloud installation. When a Private Cloud administrator submits
an application to the Marketplace, the master tenant administrator receives an email with a link to preview and
approve the application.
Alternatively, the master tenant administrator can follow these steps to approve and publish an application on
the Marketplace:
1. Open the Marketplace application from the application switcher.

2. Click and open Published Apps from the application menu bar. The Published Apps page opens.
3. In the Published Applications List 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.
6. Select the Approved check box and then click Update. The application is made available on the Marketplace
and the application publisher is notified through an email.
Enabling or disabling Marketplace in Rollbase Private Cloud

If Rollbase Private Cloud is upgraded to Rollbase 4.0 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.

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 Rollbase 4.0 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 773).
• 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, and 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. Open and configure the MarketplaceURL property in the shared.properties file (see shared.properties
on page 926) 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 on 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 and publishing an application on the Marketplace
on page 771).
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 shared.properties file.
Note: Enabling Application Directory disables Marketplace.
After enabling 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.

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:

• 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 784.
• 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

• 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.

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 365.

The following table describes when these notifications are sent to users and how to configure them:
Table 3: 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
on the Marketplace.

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

details
• A direct link to view the latest
version of the application on the
Marketplace

Notification Email Timing Notification Recipient Email Template Details
When a user installs a free Application publisher Template Name: Application

Marketplace application. Installed
• 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
definition page of Ratings

• 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
application rating.
definition page of Ratings

• The rating assigned to the
application
When a Rollbase user flags an Application publisher Template Name: Application

application as inappropriate. Flagged
definition page of Flags

• The reason why the Rollbase
user flagged the application as
inappropriate

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 779

• Use of original IDs on page 781
• Locking applications on page 782
• Attaching seed records on page 783
• Providing a test drive on page 786
• Testing and verifying application correctness on page 783
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).

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 312 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

Component Included during publication if:
Survey questions Owning object belongs to the package
Seed records 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:
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:

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 862 for information about the Login action.

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:
2. Scroll down to the Seed Records section.

3. Click Attach Records.
The Record Selector window displays.
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.
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 787 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:
2. From the More Actions menu, select Generate XML.

3. Verify that the version number is correct.
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.

Publishing to the Rollbase Application Directory

For Rollbase Private Cloud installations that have been upgraded to 4.0 from a prior version, by default the
Application Directory will be enabled as the way to publish and distribute applications. However, master
tenant 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. For those still
using Application Directory, the content in this topic provides an overview.
Publishing an application to the Application Directory makes it freely available for installation in any tenant
in the same Private Cloud instance. By default, a master tenant administrator must approve submitted
applications before they appear in the Application Directory. Private Cloud administrators can change this
behavior as needed by modifying the Published Application object in the master tenant.
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 who have it installed. See Pushing
application updates to other tenants on page 986.
2. Click Publish or Publish Updates. The button name depends on whether the application has been published
previously.
The Publish Application dialog displays.
3. Verify that the version number is correct.
4. Select a category for the application, this will be displayed in the Application Directory.
5. Enter a description. Those browsing for applications will read this, so make it as descriptive as possible.
6. Optionally, upload a logo graphic.
7. Select a Lock Status. If you select Partially Locked, you need to specify which application components
are locked by clicking the check boxes next to those components. Expand the tree to specify locking at a
fine-grained level. In the following example the Account object will be locked in the published application;
the Case object will not be locked.

8. Click Submit.
If you submitted to the Rollbase hosted Application Directory, you will receive notification on the status
of your application.
Providing a test drive

In private cloud installations where the administrator has enabled the Application Directory, application
submitters can add Test Drive capability. 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 that 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.
Administrative management of published applications

Rollbase Administrators can manage published applications from the Master Server (see Administration on
page 855 ). The Published Apps tab in the System Console provides controls for updating, deleting, and
performing other actions on published applications.

Troubleshooting 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 986.

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
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.

Component Error Fix
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
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.

Component Error Fix
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.


11
Advanced setup and administration
This section describes the setup and administration options in the Personal Setup, Administration Setup,
Support, and Monitoring Setup pages.
• Personal setup
• Administration setup
• Monitoring setup
• Support
• Language support
• Enabling Google Apps for Rollbase Private Cloud
Personal setup
Personal setup is available to all Rollbase users, including those who do not have the Administrator role.
Non-administrative users can modify personal settings by selecting My Profile from the profile menu and
selecting the appropriate category from the My Profile page. Administrative users can modify personal settings
from either the profile menu or by selecting the appropriate category from the Personal Setup section of the
Setup home page.
Personal settings are divided into multiple categories, with each category on a separate page. These categories
are:
• My Settings — Allows you to configure general user settings

Chapter 11: Advanced setup and administration
• 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 Preferences — Allows you to set your default theme and set a landing page
• My Security Settings — Allows you to enable or disable support access to your account
• Change My Password — Allows you to change your password
• 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 739 for more information.
The following topics describe the settings in each category.
My Settings page
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 748 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 743. Only an administrator user can change
these settings.
• Approver — Select if this user is allowed to be an approver (see Approvals on page 423). 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 707.
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 708 for details.

Personal setup
Third Party Settings page

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 803 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 708 for details.
To configure Rollbase to use your email account and synch 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).
• 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 page

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.

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 page on page 792.
My Preferences page
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.

Personal setup
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 578.
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 733 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

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 897.
To generate a token:
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 My Preferences page.
3. Click Save.
You can regenerate the token at any time. The new token replaces the previous one.
My Security Settings page

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.

Personal setup
Change Password page

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 719.
Recycle Bin page

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.

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
800) 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 726.
• 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 800.
• 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 800.

• 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 801, and Account administration and security settings on page 803.
• Currency Codes: Opens a view of currency codes to be used in your account.
• Exchange Rates: Opens a view to set exchange rates.
• Email Server Settings: Opens a view to configure custom SMTP server settings. For more information,
see Account administration and security settings on page 803.
• Preferences: Opens a view to set organization's preferences such as custom field validations in API
calls.
• Localization Settings: Opens a review to set organization's localization settings such as locale, number,
date, and time formats.
• Google OAuth 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 828 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.
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 use Use Following Google
OAuth 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 721.
• Authentication: Opens a view to specify users' authentication method (Rollbase Private Cloud only).
For more information, see Setting the authentication method on page 874.
• 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
761.
• 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 864 and Backup and restore on page 804
• 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 811.
• 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 813.

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:
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 617)
• 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.
• 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 719).
• Expiration Policy: Specifies the number of days before user passwords expire (see Security and access
control on page 719).
• 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 815 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 477.
• 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 707 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.
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 Third Party Settings page on page 793).
For Rollbase Private Cloud customers, email server settings are updated in the shared.properties file.
Your updated settings take effect after server's restart. If you're using multi-server configuration, copy the
updated shared.properties configuration file to all your servers.
• 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 720.
• 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
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 backups of application data.
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 file.
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 file. 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 file.
For more information about shared.properties and working with customer records, see shared.properties
on page 926 and Working with customer records on page 862.
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 862 for more information.
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:
6. Click Restore to restore data from their 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.
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 982.

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 477.
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
### ### ###,## € 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
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
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
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.
• 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:
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.
• 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.
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.

Monitoring setup
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 44):
• 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.

• 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 761).
• 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 on page 32): To initiate a product
feature discussion and participate in an ongoing discussion in the forum.

Language support
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 on page 32): 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 817 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 818 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

• 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:

Language support
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 818

• Translating application component names and labels on page 821
• Creating and using multilingual string tokens on page 825
• Translating application data on page 827
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.

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 818 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 827 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 825 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 821 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.

Language support
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:

Follow these steps to translate an application using a spreadsheet:

1. Navigate to the application's Setup Application screen. (See Editing applications on page 274).
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.

Language support
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 827 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.

Table 4: 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 273. 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 490.
Portal Portal Name, Description New Portal screen or Edit Portal screen. See
Creating a portal on page 596.
Role Role Name, Description New Role screen or Edit Role screen. See
Creating and editing user roles on page 726.
Hosted File File Name, Description New Hosted File screen or Edit Hosted File
screen. See Managing hosted files on page 617.
Batch Job Job Name New Batch Job screen, Edit Batch Job screen.
See Batch jobs on page 811.
Catalog Description New Progress Data Catalog screen, Edit

Progress Data Catalog screen. See Creating
Progress Data Catalogs for external applications
on page 717.
Object Singular Name, Plural Name, New Object screen, Edit Object screen. See
Record Name, Description Creating and managing objects, fields, and
relationships on page 297. 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 297. 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 297.
Page Tab Name, Section Title Properties screen for the page, page editor. See
Pages, the page editor, and grid controls on page
490.

Language support
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 561.
Template Template Name, Subject (email New Template screen, Edit Template screen.
template only) See Working with templates on page 350.
Chart Chart Name, X Axis Label, Y New Chart screen, Edit Chart screen. See
Azis Label Working with charts on page 471.
Report Report Name, Description New Report screen, Edit Report screen. See
Working with reports on page 448.
Gauge Gauge Title New Gauge screen, Edit Gauge screen. See
Working with gauges on page 475.
Trigger Trigger Name New Trigger screen, Edit Trigger screen. See
Trigger overview on page 381.
Workflow Process Process Name New Workflow Process screen, Edit Workflow
Process screen. See Workflow processes on page
421.
Workflow Status Status Name New Workflow Status screen, Edit Workflow
Status screen. See Workflow status on page 414.
Workflow Action Action Name New Workflow Action screen, Edit Workflow
Action screen. See Workflow actions on page 415.
Button Display Label New Button screen, Edit Button screen. See
Using buttons on pages on page 515.
Conversion Map / Map Name New map screen, Edit map screen. See Converting
Import Map records on page 329 and Importing data on page
699.
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

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:

Language support
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
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 359 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:

The following screen shows an HTML component that uses the string token:

Language support
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.

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 file of 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 file of Rollbase Private Cloud instance can enable
the use of Google Apps.

Enabling Google Apps for Rollbase Private Cloud
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 file.
5. Log into Rollbase Private Cloud.
6. Navigate to Personal Setup and configure your Google Apps account for Rollbase. For more information
about Google Apps Settings, see Personal setup on page 791.
Note: After the Rollbase Private Cloud's shared.properties file 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.


12
Installing and administering Private Cloud
The topics in this section describe how to install, configure, and administer Rollbase Private Cloud.
• Introduction
• Installation
• Administration
• Private Cloud security and access control
• Multi-server environments
• 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.
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.

Chapter 12: Installing and administering Private Cloud
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.

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 902
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 837.
• 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 842.
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.

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.

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 Application Directory
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 Application Directory 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.
be Progress\Rollbase\Pas_Instance\rollbase\config.
5. Restart PAS or Tomcat.

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.
be Progress\Rollbase\Pas_Instance\common\lib.
4. Copy the Aspose.Pdf.lic license file into the config directory of your Rollbase installation.
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 906 or Installing and running
a PAS instance as a Linux daemon on page 907.
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.

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 7 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 845 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 4.0, please read Upgrading Private Cloud to Version 4.X on
page 235 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.

• 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 838 for details.
• Console mode, which uses text-only prompts to guide you through the installation. See Installing Rollbase
using console mode on page 840 for details.
• Silent mode, which enables the installer to run without any user interaction. See Installing Rollbase using
silent mode on page 840 for details.
After installing Rollbase private cloud, proceed to Postrequisites on page 841.
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 845.
8. Click Next
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.

Installation
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 configuration file or in administrative setup. The shared.properties on page 926 file
will contain the values you enter here.
• Host Name — Host name of the desired email server

• Port Number — Desired email server port number
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 configuration file. For example, you might
want to set up an account named something like noreply@domain.com. The shared.properties on page
926 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.
20. 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 842, including:
• Specify as much memory as possible for initial and Max memory pools
• Disable system persistence
• Ensure proper UTF-8 support
• Specify <session-timeout> node value
21. 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 841.

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_4.2_WIN_64.exe install -i console
3. Follow the prompts as directed. See Installing Rollbase using the default mode on page 838 for a description
of the information you need to enter.

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 841 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_4.2_WIN_64.exe install -f response.properties -i silent


Installation
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
#Email Configuration
#-------------------
MAIL_HOST_NAME=Localhost
MAIL_PORT_NUMBER=1234
MAIL_ADMIN_ADDRESS=example@exampleDomain.com
MAIL_USER_NAME=testUser
MAIL_PASSWORD=Passsword
MAIL_USE_NONE=1
MAIL_USE_SSL=0
MAIL_USE_TSL=0
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 databases.xml file. Then, you can start the runtime components as described
in Starting components and logging In on page 851.
• 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.
• 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
Edition.

Installation
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 842.
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 shared.properties file
6. Edit the components.xml file
7. Run the Rollbase script for your database type and edit databases.xml.
8. 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

• 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>.

Installation
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
Configuring a supported database

Rollbase certifies use of the following databases (see Platforms supported for Private Cloud on page 833):
• MySQL
• OpenEdge Database
• Oracle Database
• 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 846

• OpenEdge on page 847

• Oracle on page 848
• Microsoft SQL Server on page 848
• Editing databases.xml on page 848
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 846.
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.
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, modify the Rollbase configuration file as described in "Edit databases.xml".

Installation
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.
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 databases.xml".
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
Modify the Rollbase configuration file as described in "Edit databases.xml".
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 databases.xml".
Editing databases.xml
The database.xml 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 database.xml 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:

Installation
• 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 database.xml 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 databases.xml
• 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
The following examples are in alphabetic order, by database type.

This example shows how to use a DataDirect Cloud to connect to a cloud data store with the data
source RB_DBO. The data source must have been defined and tested using the DataDirect Cloud
dashboard:
<Database name="RB" isDefault="yes" isExternal="no"
MinConnections="3"
MaxConnections="10" MaxInUseConnTimeMins="30"
MaxNotUsedConnTimeMins="1" MaxConnLifetimeMins="60"
TxIsolation="2" useTxRecovery="yes">
<Driver>com.ddtek.jdbc.ddcloud.DDCloudDriver</Driver>
<Url>jdbc:datadirect:ddcloud://service.datadirectcloud.com:443;
databaseName=RB_DBO</Url>
<DbUser>root</DbUser>
<Password>my_password </Password>
</Database>
This example shows how to specify a JDBC driver and URL to connect to a MySQL database named
RB_DBO:

MinConnections="3"
TxIsolation="2" useTxRecovery="yes">
<Driver>com.mysql.jdbc.Driver</Driver>
<Url>jdbc:mysql://localhost:3306/RB_DBO</Url>
<Password>my_password</Password>
</Database>
This example shows how to specify a JDBC driver and URL to connect to an OpenEdge database.
Rollbase includes the Progress DataDirect JDBC driver file openedge.jar. The example uses
variables that are described below:
MinConnections="3" MaxConnections="10"
MaxInUseConnTimeMins="30" MaxNotUsedConnTimeMins="1"
MaxConnLifetimeMins="60" TxIsolation="2" useTxRecovery="yes">
<Driver>com.ddtek.jdbc.openedge.OpenEdgeDriver</Driver>
<Url>jdbc:datadirect:openedge://localhost:8911;databaseName=rbdb</Url>

<DbUser>dbadmin</DbUser>

<Password>dbadmin</Password>
</Database>
In the JDBC URL, the example uses localhost:8911;databaseName=rbdb for the hostname,
port number, and database name. Note the following:
• hostname — Use localhost if the database resides on the same machine as Rollbase, otherwise
use the actual host name.
• port — Use the port number on which the Rollbase database was started before executing the
create_oedb script.
• databaseName — Use the name of the Rollbase database created when executing the
create_oedb script.
This example shows how to specify a JDBC driver and URL to connect to an Oracle database:
MinConnections="3"
TxIsolation="2" useTxRecovery="no">
<Driver>com.rb.jdbc.oracle.OracleDriver</Driver>
<Url>jdbc:rollbase:oracle://localhost:1521;ServiceName=RB_DBO;
ConnectionRetryCount=10;ConnectionRetryDelay=10</Url>
<Password>my_password </Password>
</Database>
This example shows how to use a JDBC driver and URL to connect to a SQL Server database:
MinConnections="3"
TxIsolation="2" useTxRecovery="no">
<Driver>com.rb.jdbc.sqlserver.SQLServerDriver</Driver>
<Url>jdbc:rollbase:sqlserver://localhost:1433;
databaseName=RB_DBO;
ConnectionRetryCount=10;ConnectionRetryDelay=10</Url>
<Password>my_password</Password>
</Database>
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 452 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.
After you install Rollbase, you must follow the below steps to configure PD4ML.
1. Run pd4font.properties generation command — java -jar pd4ml.jar -configure.fonts
/path/to/my/fonts/
As a result, it will produce pd4font.properties file at /path/to/my/fonts.
2. Set the FontDirectory shared property as /path/to/my/fonts/ directory. See shared.properties on page

Installation
For example, if you run the java -jar pd4ml.jar -configure.fonts C:\Windows\Fonts command
on your windows machine, you must set the FontDirectory shared property as C:\Windows\Fonts.
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
Note: To start Tomcat on Windows, you need to be logged in as an administrator using an account that has
read and write permissions for the Rollbase installation directory.
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 file. Bookmark the URL for
future use.
5. Change the temporary password.
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.
• 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 file. 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 852

• Upgrading a license without restarting on page 853
Upgrading from an evaluation license

To upgrade Rollbase Private Cloud from an evaluation version, follow these steps:
1. If you evaluated Rollbase in local environment using localhost as the host name, follow these steps to
use an external host name:
a) In components.xml, modify the URLs to point to the correct host name.
b) In the shared.properties file, modify the HostName entry to resolve #HOST_NAME tokens with the
correct host name.
2. Copy the license.xml file into the config directory.

3. Stop and restart PAS or your Web server.

Installation
Upgrading a license without restarting

To activate a license without restarting:
1. Log in to Rollbase.
2. In the top right of the screen, click the arrow next to your profile and selectSubscription Details.
3. In the Your License 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 853

• 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
==>> RSS server is starting
==>> SEARCH Server is starting
==>> STORAGE Server is starting
==>> 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 844
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 shared.properties, Update the configuration files with the correct host
databases.xml and components.xml configuration name.
files does not match the actual host name you're using.
The shared.properties file 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.
An error message mentions Java "PermGen space". Restart the server.
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.
• 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:

Administration
• Make sure that all email-related global settings in the shared.properties file 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
system-generated passwords for new users.
Login issues
If you are having trouble logging in to Rollbase and you are sure that the Web server is running:
• Log in using the admin email address specified in your shared.properties file as the user name.
• The first administrative user's password is always set to welcome. You should change this password on
the first login.
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.

Overview
Administrative users who set up customer tenants determine which applications are visible in each tenant. In
addition, the Rollbase interface is highly customizable, allowing you to replace the Rollbase logo and use your
own CSS styles.
When new users install Rollbase Private Cloud, the interface appears identical to the Progress-hosted Rollbase
interface, with the Pacific header and footer. However, you can remove these by editing shared.properties
and setting the PacificUIDisabled property to true.
Note: If your Rollbase environment is highly customized, the interface might differ slightly from the screens
shown in this documentation..
The application switcher allows you to navigate to installed applications and to setup pages.
Application switcher items include:
• Rollbase Home — The Rollbase application that contains the Rollbase calendar and the User object you
use to create user accounts
• Setup Home — A shortcut to the Setup home page, which provides access to administrative settings for
users with administrative privileges and to preinstalled applications
• Current App Settings — A shortcut to the setup page for the currently open application
• Organization Management — Contains Location, Department, Function, and Group objects, which
allow you to set up complex access control. See Location/department/function permissions on page 748 for
more information.
• System Console — Contains objects for managing customer tenants, subscribers (users of customer
tenants), and applications in the Application Marketplace
• ISV Partner — Contains objects for managing ISVs and partners who will resell applications
• Support Center — Contains objects for managing support of your customer tenants
• Approvals — Contains objects for adding approval workflows to your applications
• CRM — The sample CRM application that is also available in the public cloud. You can customize this
application to manage your own customers.

Administration
Monitoring system components

From the System tab of the System Console application, you can view the current status of all Rollbase
system components.
From this page, you can:
• View the status of all production servers

• View the status of all databases.
• View the hostname for each production server, including information about its processor, RAM, OS, Java
version, and memory consumption.
• Click a link in the Threads column to check the current status of all system Java threads for that component.
• Click a link in the Connections column to check the status of all database connections.
• Click the shared.properties tab to view the current settings of all shared properties.
• Click Query in the Databases table to execute an SQL query on the database.
• Click Edit in the Databases table to modify database properties.
• Click a production server name link to open the Component Information page for that server. This page
contains more detailed information, including a list of currently loaded customers and logged in users, as
well as a list of import, batch, and customer creation jobs currently running and in the queue.

From the Component Information page you can do the following:
• Check whether a customer tenant is loaded.

• Click the link to force load or unload of a particular customer from the production server cache. If you
change settings such as expiration date or limitations while the customer tenant is in use, you need to
unload and load to pick up the new settings.
Note: Unloading a customer tenant from the production cache will log out all users currently logged into
that tenant, including any API sessions.
From sub-menus of the System tab you can:
• Select Master Zone to monitor logs:

• Click Logs Related to All Customers to monitor customer logs. AllJobs.log and AllErrors.log
are particularly important.
• Click Master Server Logs to monitor Master Server logs.
• Click App Server Logs to monitor logs for the application server.
Note: Rollbase performs log operations in asynchronous mode. There might be a slight delay between a
when an event is logged and it is written to the file and is viewable.
• Select Reindex to reindex the Master Zone and/or a group of selected customers.
• Select Debug to set the ID of an object definition or customer for debugging purposes. When you set an
object definition ID, all SQL queries used to list records of this definition will be logged in the query.log
file. You can set a customer ID to log all SQL queries for that customer in query.log or to debug search
indexing for that customer in search.log.

Administration
Monitoring system health

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.
The CleckLoginURL component property on MASTER component enables this system health check and it
also sends status emails to Rollbase admin if health check fails. See Component specific properties for more
information. See Component specific properties on page 918 for more information.
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 864.
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 861 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 file 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.
4. In the Customers List section, click New Customer.
5. Enter the following information:
• Database — select the database to hold this customer's data.

Administration
• Plan — select a pricing plan to determine default limits on the number of records, fields and other
resources allowed for this customer. See servicelevel.xml on page 925 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 861
for details.
• 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 926
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 725 for a list of administrative permissions you can grant to a
non-administrative roles.
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 296 for more information.
4. Follow the steps in Creating a new customer record on page 860 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:

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 761.
• Edit: Modify the customer record. Requires edit permission.
From the More Actions drop-down menu, do any of the following:
• Delete: Delete 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.

Administration
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.
• 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 761.
• 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 804 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 set the IsAsposePDFParserEnabled shared
property to true. By default, this property is set to false.
• 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 set the IsAsposeDocParserEnabled shared
property to true. By default, this property is set to false.
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 set the IsAsposeDocxParserEnabled
shared property to true. By default, this property is set to false.
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.

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 862).
2. Create and register a new empty database (see Adding a new database for use with customer tenants on
page 869).
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 860).
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 862.
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.

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:


Administration
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.
Managing databases
The databases.xml 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 application 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 869
• Creating custom database indexes on page 871
• Adding columns to a Private Cloud database on page 872

Administration
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:

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

Administration
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.
• 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 databases.xml
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);
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.

Administration
Application Directory, Marketplace, and support portal

Your Rollbase customers can publish their applications to either the shared Applications Directory or to
Marketplace. See Using the Progress Rollbase Marketplace on page 766 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.
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 Applications Directory.
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 in the Applications Directory 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 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
portal. You can also edit properties of the Test Drive field.
6. Open the Application Directory portal and locate the published application. On the view page you should
see a Test Drive button. If Test Drive is configured correctly, this button will be enabled.
When a visitor to the Applications Directory portal 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 985.
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 897 — 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 719.
The following topics describe Private Cloud security options and how to configure them.
Supported methods of authenticating users

Rollbase provides a password authentication mechanism that is configured internally or allows you to use an
external system for authentication.
The authentication mechanisms are categorized as:
• Password authentication on page 875

• External authentication on page 881
Configuration of the different user authentication methods is discussed in detail in the following topics.
Setting the authentication method

The following steps describe how to set the authentication method when logged into Rollbase Private Cloud
as an administrator:

1. From the application menu in the banner, select Setup Home.

2. Under Administration Setup, click Authentication.
The Authentication Type screen opens:
3. Choose one of the following authentication types:
• Password: For details, see Password authentication details on page 876.

• LDAP: For details, see LDAP authentication details on page 883. 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 LDAP advanced authentication details on page 883. This supports
authentication across multiple user groups.
• HTTP Post: For details, see HTTP POST authentication details on page 885.
• HTTP Get: For details, see HTTP GET authentication details on page 886.
• OpenEdge: For details, see OpenEdge authentication details on page 886.
• Windows (Kerberos): For details, see Kerberos authentication details on page 890
• SAML/ADFS: For details, see SAML/ADFS authentication details on page 891
4. Click Next.
The next page allows you configure the selected authentication method. See the topic for your selected
method for details.
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 365 for more information.

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.
Password authentication details

If you choose Password as your authentication method while Setting the authentication method on page 874,
specify the following values to configure your Password authentication for Rollbase:
Table 5:
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 876.
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 878 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 879.
Security Questions Security questions users must answer to authenticate

to Rollbase. For more information about security
questions, see Security questions for authentication
on page 898.
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 securityLevel.xml on page 924). 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
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 497 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 876 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:


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 Password authentication details
on page 876, 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.
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 365 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:


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.

External authentication
If you choose to use external authentication instead of Rollbase password authentication, the following external
authentication methods are supported by Rollbase:
• 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.
• SAML/ADFS authentication details on page 891 — Rollbase authentications users using Security Assertion
Markup Language (SAML).
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 882 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:

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.

LDAP authentication details

If you choose LDAP as your authentication method while Setting the authentication method on page 874, specify
the following values to configure Rollbase to authenticate users using your LDAP system:
Table 6:
Field Description
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.
LDAP advanced authentication details

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 Setting the authentication method on
page 874, specify the following values to configure Rollbase to authenticate users using your LDAP system:
Field Description
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

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.
HTTP POST authentication details

If you choose HTTP POST as your authentication method while Setting the authentication method on page
874, specify values for the following fields to set up a Post call to authenticate to an external system::
Table 7:
Field Description
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> ).

HTTP GET authentication details

If you choose HTTP GET as your authentication method while Setting the authentication method on page 874,
specify values for the following fields to set up a Get call to authenticate to an external system:
Table 8:
Field Description
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> ).
OpenEdge authentication details

If you choose OpenEdge while Setting the authentication method on page 874, 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.

Field Description
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.

Field Description
Manages Password Enables the following password-management options:
• Expiration Policy: The number of days until a user's password expires.
The minimum value for this is determined by the shared property
ExpirationPolicy for master tenants and by the shared property
MinExpirationPolicy for other tenants.
• 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 898 for information about
security questions. See Configuring security questions on page 898 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 888.
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.
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.

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.

After updating the OERealm service interface class file, you must restart the server for the changes to take
effect.
Kerberos authentication details

If you choose Kerberos while Setting the authentication method on page 874, 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 file 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.
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.
SAML/ADFS authentication details

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 will be configured separately for each tenant, perform the following tasks:
1. Configure API authentication. SAML/ADFS authentication must use either API token or custom API
authentication. See API authentication on page 897 for details.
2. Configure the Rollbase instance to enable SAML/ADFS authentication.
3. 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 API authentication. SAML/ADFS authentication must use either API token or custom API
authentication. See API authentication on page 897 for details.
2. Configure the Rollbase instance to enable SAML/ADFS authentication.
3. Configure SAML/ADFS authentication details for all tenants
See the following videos for detailed demonstrations of configuring SAML/ADFS authentication:
• Configuring SAML in Rollbase Private Instance with Salesforce as IDP-Part 1

• Configuring SAML in Rollbase Private Instance with Salesforce as IDP-Part 2
• Configuring SAML with Rollbase and Okta
See the following topics for details about configuring SAML/ADFS authentication:
1. Configuring the Rollbase instance to enable SAML/ADFS authentication on page 892
2. Configuring SAML/ADFS authentication details for a tenant on page 893
3. Configuring SAML/ADFS authentication details for all tenants on page 895
4. Example SP metadata file on page 896
Configuring the Rollbase instance to enable SAML/ADFS authentication

Before any tenant can configure SAML or ADFS authentication details, 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. Copy the keystore (Progress.jks in the above example) to the config directory of your Rollbase
installation, for example, C:\Progress\Rollbase\Pas_Instance\rollbase\config.
3. Export the public key certificate from the keystore using Keytool as shown below:
keytool -export -keystore Progress.jks -alias server -file MyCertificate.cer

4. 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 896 for an example of an SP
metadata file.
5. Place the SP metadata file in the Rollbase instance's config directory, for example,
C:\Progress\Rollbase\Pas_Instance\rollbase\config.
6. Update the shared.properties file as follows:
• SPKeyStoreFile — The name of the keystore. In the above example, this is Progress.jks.
• SPKeyStorePassword — The keystore password. In the above example, this is myPassword.
• SPKeyStoreAlias — The keystore alias. In the above example, this is server.
• SPMetadataFile — The name of the SP metadata file (see step 4)
• 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.
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 details for a tenant

Follow these steps to configure SAML or ADFS authentication details for a tenant:
1. Select SAML/ADFS as the authentication method as described in Setting the authentication method on
page 874.
2. Download the SP metadata file by clicking Download SP Metadata. You will need values from this file in
step 6.
3. 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.
4. After configuring the IdP as described in step 4, 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 892 for more information.
5. Specify the following values to configure a Rollbase tenant to authenticate users using SAML or ADFS:

Table 9:
Field Description
Name The name for the SAML configuration
Issuer (IDP Entity ID)/ADFS This is the value of the entityID attribute of the EntityDescriptor
Entity ID element in the IdP metadata file.
Identity Provider Metadata/ADFS The IdP metadata file. Upload the file you obtained or created in step
Metadata 4.
Service Provider EntityID/Relying The entity ID of the service provider. This is the value of the entityID
Party Entity ID 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. To do this, it is mandatory to map the
Rollbase attribute loginName as at least one attribute mapping is
required. 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.
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 1269 and getAuthentication on page 1233
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.
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.

Configuring SAML/ADFS authentication details for all tenants

You can configure SAML/ADFS authentication to apply globally to all tenants for the instance.
Follow these steps to configure SAML/ADFS authentication globally:
1. Configure the instance to enable SAML authentication.
2. 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.
3. After configuring the IdP as described in step 2, 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. You must save this
file in the Rollbase config directory (required), for example,
C:\Progress\Rollbase\Pas_Instance\rollbase\config. This file is referred to as the IdP metadata
file in the next step.
4. Set values for the following shared properties in the shared.properties file.
AuthOverrideAtCustomer A Boolean value specifying whether tenants are allowed to select a

different authentication method. If true, tenants can use a different
authentication method. If false, all tenants must use the
authentication method indicated by the DefaultAuthType property.
DefaultAuthType SAML
SAMLLogoutURL A custom URL that can be configured by the SAML/ADFS master

administrator to redirect the user after logout.
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.
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.
IdPMetadataFile The IdPmetadata file name. See step 3.

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:
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.
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>

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
Enabling tokens for API authentication on page 897 for information about enabling API tokens. See My
Preferences page on page 794 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 shared property APIAuth. See
shared.properties on page 926 for details.
The table below lists the available authentication methods and the authentication mechanisms supported by
each:
Authentication method API mechanisms supported

Password Password, API token, Custom
LDAP LDAP, API token, Custom
LDAP advanced LDAP advanced, API token, Custom
HTTP POST HTTP POST, API token, Custom
HTTP GET HTTP GET, API token, Custom
OpenEdge OpenEdge
Kerberos API token, Custom
SAML/ADFS API token, Custom
Custom Custom
Enabling tokens for API authentication

Rollbase Private Cloud supports using tokens for authentication in login APIs instead of the user's password.
This feature is available for all authentication methods except for OpenEdge and custom authentication. To
use tokens for authentication, an administrator must enable them for the tenant as follows:
1. On the Setup Home page, click Authentication from the Administration Setup area.
2. On the Authentication Type page, click Next.
3. In the API Authentication area, select API Token and click Save.
The screen below shows the API Authentication options for Password authentication. See API
authentication on page 897 for the choices available to each authentication method.

4. After API tokens are enabled, users in that tenant can generate API tokens See My Preferences page on
page 794 for details about generating API tokens.
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 898.
For information about selecting and answering security questions, see Selecting and modifying your security
questions on page 25.
Configuring security questions

To configure security questions:


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.
See Selecting and modifying your security questions on page 25 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. Open the file shared.properties in a text editor. This file is in the config folder of the master server
instance.
2. Find the property HostName.
3. 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.
4. Save the file.

5. Restart the server.

Multi-server environments
If you are using a licensed version of the product:

1. Open the file components.xml in an editor. This file is in the config folder of the Master Server instance.
2. This file contains several instances of the element ExternalRoot, for example,
<ExternalRoot>http://{!#HOST_NAME}/master/</ExternalRoot>.
3. In each ExternalRoot element, change http to https.
4. Save the file.
5. Restart the server.
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 RollbaseRollbase 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.
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 914 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 Apache server to perform the routing of requests to the Tomcat instances.
You can have as many of these Apache 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.
How you set up your environment depends on whether you are using PAS or configuring your own Apache
Tomcat system:
• Distributing load with PAS on page 902

• Distributing load with Apache and Tomcat on page 907
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 902 and following the procedures described in Adding auxiliary servers on page 912.
• 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.
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.)
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.
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)

See Create an instance (create) on page 953 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.

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

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 Apache and Tomcat

The following graphic illustrates a multi-server architecture using 4 servers:
• Server 1: Apache configured to use Workers

• 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)
You can enable appliance-based load balancing in front of Apache servers if you have multiple Apache servers
configured (which would be recommended with such a large number of users) but this should not be done for
Tomcat servers.

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 Apache servers with Workers 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:
• Host 3: master.war, rest.war, router.war, search.war, storage.war, webapi.war

• Host 4: prod1.war
• Host 5: prod2.war (renamed version of downloaded prod1.war)
Configuring Apache and Tomcat for Private Cloud

You can configure an Apache server as a front-end for your Tomcat instances. After you have installed Apache
and each of your Tomcat instances, you will need to configure Tomcat Workers in Apache to tell it how to route
incoming requests to Rollbase. Apache has extensive documentation on this at
http://tomcat.apache.org/connectors-doc/generic_howto/quick.html.
Progress Rollbase only supports Tomcat 8.0.30 and 8.5.4. First verify that you have Tomcat installed on the
same server as Apache. Then, follow these steps to configure Apache and Tomcat for Rollbase Private Cloud:
1. Install the JK Module.
2. Create a workers.properties file.
3. Configure the httpd.conf file.

Install the JK module

Verify that you have the JK module in your Apache modules directory. JK is the protocol used to communicate
between Apache and Tomcat. You will need to locate and download the version of mod_jk.so that applies
to the version of Apache you are running. You can typically find the latest versions of mod_jk.so here:
http://tomcat.apache.org/download-connectors.cgi/
A typical location for the Apache modules directory on a Windows machine would be:
C:\Program Files\Apache Group\Apache2\modules\
Create a workers.properties file

Once you have the JK module installed, you will need to create a new file called workers.properties in
Apache's conf directory (the same location that httpd.conf resides in). You can support any number of
Production Server components in a multi-server architecture by pointing to them with worker properties as
shown in the example below. You would duplicate the worker.prod1.x entries for each Production Server
instance you have set up.
The workers.properties file should look something like the following. Note that each worker.xyz defines
a worker named xyz. These workers will referenced by this name in Apache's httpd.conf file.
# Tomcat home directory on same server as Apache

workers.tomcat_home=C:/Tomcat6.0
# Java home directory on same server as Apache
workers.java_home=C:/jdk6.0
# List of workers (defined in httpd.conf; one for each Tomcat)

worker.list=master,prod1
# The "master" worker is your Rollbase master server

# type should always be ajp13 (AJP13 is the protocol used to communicate with Apache)
worker.master.type=ajp13
# host should be the network name or IP of the target server
worker.master.host=335090-web2
# port should be 8009 by default; do not change this unless you reconfigured Tomcat
to accept AJP requests on a different port
worker.master.port=8009
# The following parameters should not be changed without detailed understanding of
Tomcat workers
worker.master.lbfactor=1
worker.master.socket_timeout=0
worker.master.socket_keepalive=1
worker.master.connection_pool_timeout=60
worker.master.connection_pool_size=300
worker.master.connection_pool_minsize=50
# Create a "prodX" worker for each of your Rollbase production server Tomcats as shown
here
worker.prod1.type=ajp13
worker.prod1.host=335091-web2
worker.prod1.port=8009
worker.prod1.lbfactor=1
worker.prod1.socket_timeout=0
worker.prod1.socket_keepalive=1
worker.prod1.connection_pool_timeout=60
worker.prod1.connection_pool_size=300
worker.prod1.connection_pool_minsize=50

Configure the httpd.conf file

Once you have installed mod_jk.so and created your workers.properties file, you need to configure
your httpd.conf file to enable mod_jk and define your workers. To enable mod_jk add the following line
to httpd.conf:
# Loads the Jakarta Tomcat connector protocol module

LoadModule jk_module modules/mod_jk.so
Add the following to define workers configuration:

# Tells the module the location of the workers.properties file
JkWorkersFile "C:/Program Files (x86)/Apache Software
Foundation/Apache2.2/conf/workers.properties"
# Specifies the location for this module's specific log file

JkLogFile "C:/Program Files (x86)/Apache Software
Foundation/Apache2.2/conf/logs/mod_jk.log"
# Sets the module's log level to info

JkLogLevel info
# Uses the below worker mounts for all virtual hosts; otherwise disabled for SSL
JkMountCopy All
Now for each named worker in workers.properties, you need to specify the subdirectories that should be
available in inbound requests. For the Master Server, Rollbase requires the following:
JkMount /workflow master
JkMount /workflow/* master
JkMount /storage master
JkMount /storage/* master
JkMount /webapi master
JkMount /webapi/* master
JkMount /search master
JkMount /search/* master
JkMount /rest master
JkMount /rest/* master
JkMount /rss master
JkMount /rss/* master
JkMount /master master
JkMount /master/* master
JkMount /router master
JkMount /router/* master
For each production server add the following code (make sure the name prodX corresponds to the name of
each production server worker you defined in workers.properties):
JkMount /prod1 prod1
JkMount /prod1/* prod1
Apache troubleshooting
If you have trouble getting a multi-server environment to work, it is helpful to:
• Review the apache error logs for configuration errors.

• Review the mod_jk log file for JK related configuration errors.
• Review documentation at tomcat.apache.org.
If all else fails, contact Progress through the Community forums or open a support ticket.

Configuring multiple instances of Rollbase components

With the appropriate license, you can distribute Rollbase components across multiple hosts. The architecture
shown in the following diagram illustrates one way components could be distributed if you are using Apache
and Tomcat:
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. You should use this domain name for all external URLs in the
components.xml file. The example configuration shown in the illustration requires a Rollbase license for
three servers.
To set up the example architecture shown above, follow these general steps:
1. Install PAS or Apache and Tomcat as described in Distributing load with PAS on page 902 or Distributing
load with Apache and Tomcat on page 907
2. Use the multi-server license provided by Progress for the Rollbase Master Server installation.
3. Install the components on their respective hosts.
4. Edit the components.xml file for the Master Server to include entries for all system components. For
internal URLs accessed from within your firewall, you must use IP addresses for the physical servers. For
external URLs accessed from outside your firewall, it is best to use the {!#HOST_NAME} token. See
components.xml on page 917 for details.
5. Configure your Web server (PAS, Tomcat, or Apache) to provide access to both production servers through
a single external URL.
6. Start the database(s).
7. Start the Web server that is hosting the Rollbase Master Server instance.
8. Start the Web server on the hosts for production components.
9. Navigate to the System Console application System tab to verify that all of your components can be
monitored from the Master Server. Make sure that production servers have the correct parameters.

When the system is running, you can add production servers up to the limit enforced by your license without
stopping and restarting the Master Server. Production servers should only be started after they have been
configured.To add components, you must stop and restart the Master Server as described in Adding auxiliary
servers on page 912.
Adding auxiliary servers

In the Rollbase multi-server edition, you can also run multiple instances of:
• Master Servers
• Production Servers
• REST Servers
• Router Servers
• SOAP Servers
• Search Servers
• Storage Servers
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.
Before installing of multiple auxiliary servers , you must make note of the following considerations:
• At most, one server of each type can be installed on a virtual or physical machine.
• Edit the components.xml file in the Master Server config directory:
• name attributes must be unique.
• type attribute must match the type of component
• Make sure that the name of the WAR file used to install every server matches the name used in
components.xml. This might require renaming, as described in the example below.
• Copy the license file to the installation config directory on each host.
• On the host machines, define an environment variable for the type of server they will run as summarized
below.
• When you are finished, restart the Master Server first and then the production and auxiliary servers.
Environment Variable Description Default Value
MASTER_SERVER Name of Master Server as defined MASTER

in the components.xml file.

Environment Variable Description Default Value
PROD_SERVER Name of Production Server as PROD1

defined in the components.xml
file.
REST_SERVER Name of REST Server as defined REST

ROUTER_SERVER Name of Router Server as defined ROUTER

SOAP_SERVER Name of SOAP Server as defined WEBAPI

SEARCH_SERVER Name of Search Server as defined SEARCH

STORAGE_SERVER Name of Storage Server as defined STORAGE

Example for Multiple PROD servers

Consider an example where two PROD servers are installed on two physical machines. The components.xml
file describes them as follows:
<Component name="PROD1" type="PROD">
<DisplayName>REST1 Server</DisplayName>
<InternalRoot>http://server1:8080/prod1/</InternalRoot>
<ExternalRoot>http://{!#HOST_NAME}/prod1/</ExternalRoot>
</Component>
<Component name="PROD2" type="PROD">

<DisplayName>REST2 Server</DisplayName>
<InternalRoot>http://server2:8080/prod2/</InternalRoot>
<ExternalRoot>http://{!#HOST_NAME}/prod2/</ExternalRoot>
</Component>
The additional configuration required includes:

1. Setting a PROD_SERVER=PROD1 environment variable on Server 1.
2. Renaming the WAR file on Server 1 to PROD1.war
3. Setting a PROD_SERVER=PROD2 environment variable on Server 2.
4. Renaming the WAR file on Server 2 to PROD2.war
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. To assign customers to a dedicated server:
1. From the application switcher, click System Console.

2. Edit the production server in one of the following ways:

• If you are setting up a new production server, follow the steps described in Adding auxiliary servers on
page 912 and check the box to indicate the server will be dedicated to a subset of customers and skip to
Step 4
• If the production server exists and has not been configured to accept dedicated customers, follow the
procedures in Step 3:
3. To configure an existing production server:

a) Stop the production server.
b) From the System tab, click the inactive production server's name.
An error message displays.
c) Click the link in the error message to edit the server.
d) Check the Check if the server is dedicated checkbox.
e) Click Save.
4. Edit the customer records for the customers you want to assign to the production server:
a) Select the Customers tab.
b) Find the appropriate customer and click Edit.
c) Scroll down to the Zone Properties section:
d) From the Dedicated Server menu, 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 hazelcast.xml file. If the machine running active components goes down, the components
on the standby machine are promoted to be the active components. If any machine in the cluster goes down,
Rollbase sends an email to the administrator. When the machine starts up again, its components will be the
standby components.

The diagram below shows the recommended architecture for high availability in Rollbase:
In the diagram, each node is a host. This configuration requires a minimum of six nodes to run Rollbase
components, plus a minimum of two Apache nodes, Amazon Cloud Services with ELB, and whatever is required
to run a highly available database:
• Node1A and Node1B — Run the Master server, Router server, REST server, and SOAP server
• Node2A and Node2B — Run the Production server. Note that if you have multiple Production servers, each
must run on a different machine.
• Node3A and Node3B — Run the Storage server and the Search server
• Apache 1 and Apache 2 — A load-balanced high availability Apache cluster. This is required for high
availability in Rollbase 4.3. See An Active/Passive Apache Web Server in a Red Hat High Availability Cluster
• AWS — Amazon Web Services with Elastic Load Balancing. This is required for high availability in Rollbase
4.3.
For the database Rollbase uses, refer to your database vendor for their high availability features.
See Configuring multiple instances of Rollbase components on page 911 for information about configuring
components on multiple nodes.
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 842 for more information.
To configure high availability:
• Set the property IsHACluster in the shared.properties file to true to enable high availability.
• The file hazelcast.xml, which is in the config directory, for example,
C:\Progress\Rollbase\Pas_Instance\rollbase\config, controls which nodes are members of
the cluster, heartbeat detection timing, and other aspects of high availability. It contains the following
elements. Progress recommends leaving most elements at their default values. However, you must add
your cluster members to the members element.
• port element — The port number. Defaults to 5701. Can be any value from 5701 through 5710.
• members element — A comma-separated list of the IP addresses or hostnames of all members of the
cluster.
• property element with name="hazelcast.heartbeat.interval.seconds" — The time interval,
in seconds, to send a heartbeat in a cluster. Defaults to 5.

• property element with name="hazelcast.max.no.heartbeat.seconds" — The maximum time,

in seconds, after which a non-responsive node is considered to be down. Defaults to 30.
• property element with name="hazelcast.master.confirmation.interval.seconds" — The

time interval, in seconds, for confirmation from the master node. Defaults to 30.
• property element with name="hazelcast.max.no.master.confirmation.seconds" — The

maximum time, in seconds, after which a non-responsive master node is considered to be down. Defaults
to 120.
• property element with name="hazelcast.socket.server.bind.any" — Helps to control socket

bind behavior. Do not change the value of this element.
• listener elements — Helps to control heartbeat behavior. Do not change the values of these elements.
• On each node running Rollbase components, set the environment variable RB_NODE_NAME to a value
representing that node in the cluster. Each value must be unique in the cluster. If you are using a Tomcat
deployment, it is best to set environment variables using setenv.bat/sh in the tomcat/bin directory.
You will use the value of this environment variable in the components.xml file.
• Edit the components.xml file to include the following:

• Add a node attribute to each Component element that refers to the node on which it is deployed. The
value is the same as the value of the environment variable RB_NODE_NAME. For example, if
RB_NODE_NAME is set to Node1A, the corresponding Component element would look like the following:
<Component name="MASTER" type="MASTER" node="Node1A">

<DisplayName>Master Server</DisplayName>
<InternalRoot>http://mymachine.mycompany.com:8080/master/</InternalRoot>
<ExternalRoot>http://mymachine.mycompany.com/master/</ExternalRoot>
<Props>
<ResourcesCheck>2</ResourcesCheck>
<ExpirationDays>30</ExpirationDays>
</Props>
</Component>
• Add a list of Node elements representing each node in the cluster with a name attribute specifying its
node name (the value of the environment variable RB_NODE_NAME) and a role attribute specifying its
role. The value of the role attribute is arbitrary but must be the same for the two nodes that will act as
an active/standby pair – the role attribute represents the node's group in the cluster. For example, the
entries for the nodes from the above diagram would look like the following:
<Node name="Node1A" role="MASTER AND OTHERS"></Node>
<Node name="Node1B" role="MASTER AND OTHERS"></Node>
<Node name="Node2A" role="PRODUCTION"></Node>
<Node name="Node2B" role="PRODUCTION"></Node>
<Node name="Node3A" role="STORAGE AND SEARCH"></Node>
<Node name="Node3B" role="STORAGE AND SEARCH"></Node>

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.
components.xml
This XML file has a Component element for each system component, that is, each component deployed with
a WAR file. It also has a Node element for each component that is a cluster member for high availability; see
Configuring high availability on page 914 for more information. If you want to add additional components, you
need to edit the components.xml in the config directory of the Master Server and restart Rollbase to have
the configuration take effect. If you change the default port 8080 or use a host name other than localhost,
please make sure that InternalRoot values are properly adjusted for each component.
Since InternalRoot parameters are used for communications behind firewall, Progress recommends the
following to improve performance:
• Do not use the HTTPS protocol

• Use localhost or an explicit IP address instead of host name of your web server
Each Component node has the following elements:
XML Description
Node/Attribute
name A unique name for this component used internally by the system.
type (attribute) The type of this component. Can be one of the following: MASTER, PROD, REST, ROUTER,
SEARCH, STORAGE, WEBAPI
Note: If your license does not support multiple servers, you cannot have multiple nodes
of the same type.
node When configuring high availability, the name of the node. Its value is the same as the
value of the environment variable RB_NODE_NAME for that node. See Configuring high
availability on page 914 for more information.
DisplayName The display name for this component.

XML Description
Node/Attribute
ExternalRoot The URL to the root of the Web component as seen from outside of your firewall.
The{!#HOST_NAME} token will be automatically substituted by a host name from your
license file or by the HostName parameter specified in shared.properties. This
URL is used for external access to components. Example:
<ExternalRoot>http://{!#HOST_NAME}/master/</ExternalRoot>
For any plan other than a free evaluation, ExternalRoot must contain the HostName
parameter as specified in your license.xml. You cannot deploy Rollbase on a domain
other than the one for which it was licensed.
To use HTTPS for all external access, modify each ExternalRoot element to user
https instead of http and modify the port number in the shared.properties on page
926 file.
InternalRoot URL to the root of the web component as seen from inside your firewall (this can be the
same as ExternalRoot). This URL is used for internal communication between
components. Example:
<InternalRoot>http://localhost:8080/master/</InternalRoot>
Props (optional) Contains component-specific properties, see Component specific properties on page
918.
When configuring high availability, each Node element has the following attributes:
• name — The value of the environment variable RB_NODE_NAME for that node
• role — The node's group in the cluster. This must have the same value for each active/standby pair. For
example, if you have two production servers configured, their Node elements would look similar to the
following:
<Node name="ProdA" role="PRODUCTION"/>
<Node name="ProdB" role="PRODUCTION"/>
Component specific properties

This topic describes optional component-specific properties that you can specify in components.xml on page
917

Component Property Description Default Value
MASTER ResourcesCheck The amount of time (in 1

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.
MASTER ExpirationDays Number of days for free 30

trial to SaaS customers (if
0, the Free Trial box will
not be displayed in the
sidebar and trials will have
no expiration date).
MASTER CleckLoginURL Enables system health true

check and sends status
emails to Rollbase admin
if health check fails.
If set to false, the system
health check is disabled.
MASTER and PROD N ImportJobsExecutorThreadCount Enables the customers to 1

set the thread count of the
import job scheduler that
runs import jobs
simultaneously. Set a
value (1 to 5) for the
thread count for the import
job scheduler that runs the
import jobs.
PROD N Power A decimal number 1.0

between 0.5 and 2.0
indicating relative
computational power of a
production server. Servers
with higher power will get
a higher load.
PROD N isDedicated If set to true, the false

production server will only
handle the load for
selected customers.

ROUTER StatusCheckInterval Interval in minutes 10

between checks of status
for production servers.
ROUTER SynchIntervalMins Interval in minutes to 10

synchronize cached
metadata for large
customers loaded on
multiple servers.
SEARCH IndexDir Directory to store Lucene ROOT/search, where

index files. ROOT is shared
Rollbase
directory60
SEARCH CloseAfterMin Remove metadata from

cache if it is not being
used for specified number
of minutes.
SEARCH LockTimeoutSec Timeout, in seconds, to 30

obtain a lock for index
writing.
SEARCH RamBufferMB Size of RAM buffer, in MB, 64

for indexing operations.
SEARCH MaxSearchResults Max number of search 200

results to bring back for a
single full text search.
SEARCH IndexChangeSyncDelaySecs Max time (in seconds) 5

between an index change
and it being visible for
search
STORAGE StorageDir Directory to store ROOT/storage, where

uploaded files, logs, ROOT is shared
templates, etc. Rollbase directory
STORAGE LogDir Directory to store log files, Same as StorageDir

if log files should be kept
in separate location
STORAGE LogFormat The log4j format for log [%d] %m%n

messages.
STORAGE MaxBackupIndex Determines how many 1

backup files are kept
before the oldest is
erased.

STORAGE CleanupDays Delete log and backup 0

files older than specified
number of days (if
specified value > 0).
STORAGE CloseAfterMin Close log4j logger after 30

number of minutes of
inactivity.
STORAGE LogFileSize Maximum size of particular 300KB

log file, such as
main.log.
STORAGE BatchJobsExecutorThreadCount Enables multiple threads 1

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 5) for the thread count
for the Executor Service
that runs the batch jobs.
STORAGE MaxSystemBackups Max number of system 7

backup files to keep per
customer. The system will
delete older files if this
number is exceeded.
STORAGE EventCheckMins Interval in minutes 1

between checks to run
matured delayed triggers.
STORAGE ResourcesCheck The amount of time (in 1

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.

databases.xml
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
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.

XML Node/Attribute Description
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
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)
events.xml
This system file contains definitions for trigger types available in the system. Rollbase can provide more
information to paying customers regarding how to develop and enable your own types of triggers for integration,
etc. Progress recommends you do not modify this file unless you develop custom triggers.
Note: Custom triggers developed by Private Cloud customers must be registered in events.xml (Developing
a custom trigger on page 390)
fieldgroups.xml
This file contains definitions for object attributes such as Location. Each attribute comes with a group of fields.
Experienced Private Cloud administrators can add their own object attributes here.
legacyobjects.xml
This system file contains definitions for system tables, which can also be treated as object records for reporting
purposes. Rollbase can provide more information to paying customers on how to integrate legacy database
tables. Progress recommends that you do not modify this file.

listitems.xml
This file contains a list of shared picklist Items (countries, states, etc.) to be added to each tenant during
customer creation. You can modify this file.
license.xml
Progress provides this file to paying customers. Save the license file in the config directory and restart your
application server.
Note: Altering the contents of the license file will cause a system error.
securityLevel.xml
This file defines available security levels. See Built-in security levels on page 876 for more information. You can
modify this file and change the default levels or add more levels according to your security needs.
A SecurityLevel XML node with the attributes shown in the example below represents each level. No default
values exist, so make sure to set a value for each property.
Example:
<SecurityLevel level="1" name="Low"
inactiveSessionExpireMins="240" loginSessionExpireMins="480"
maxFailedLogins="0" blockTimeMins="0" lockExpirationMins="120"
minPasswordLength="6" nonLettersInPassword="false"
caseSensitivePassword="false"
sequentialCharsInPassword="true"
/>
XML Attribute Description
Level Numeric unique ID for this level
Name Display name
inactiveSessionExpireMins Expire user session after being idle for a number of

minutes
loginSessionExpireMins Expire user session after a number of minutes from

login
maxFailedLogins Temporary block user account after a number of

unsuccessful login attempts
blockTimeMins Block user account after unsuccessful login attempts

for a number of minutes
lockExpirationMins Expire record's lock after a number of minutes
minPasswordLength Minimum number of characters in users' passwords

nonLettersInPassword If set to "true" - users' passwords must include at least

one non-alphabetical character
caseSensitivePassword If set to "true" - users' passwords are case-sensitive

(case-insensitive otherwise)
sequentialCharsInPassword If set to "false" - sequential numbers of letters are not

allowed in users' passwords.
servicelevel.xml
This file defines available service levels. A service level is assigned to each customer at creation time. You
can modify this file to change default levels or to add more levels according to your business needs.
Each service level is represented by an XML node with the following attributes (no default values are used):
Note: Note: The following values defined in the service level are used only as default values and can be
overridden per individual customer: maxUsers, maxObjRecords, maxObjectDefs, maxFieldDefs,
maxPortals, maxApplications.
Level Numeric unique ID for this level
Name Display name
maxUsers Maximum number of user accounts which can be

created
maxObjRecords Maximum number of object records which can be

created
maxObjectDefs Maximum number of object definitions which can be

created
maxFieldDefs Maximum number of field definitions which can be

created
maxPortals Maximum number of portals which can be created
maxApplications Maximum number of applications which can be created
maxApiHitsDaily Maximum number of API hits per 24 fours
maxStorageMB Maximum size of locally stored files (in MB)

maxForeignLangs Maximum number of foreign languages which can be

assigned to customer (from 0 to 4)
maxDelayedEvents Maximum number of delayed triggers for 24 hours
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.
• The shared.properties file uses ISO-8859-1 encoding. If you wish to include multi-byte characters in
this file, use Unicode \u notation such as: \u00A9 for a copyright symbol.
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, see Language support on
page 815.
Default: None (must be specified prior to server start up)
AdminEmail Email address of the first administrator user created during installation
Default: None (must be specified prior to installation)
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

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
AllowAdminLessTenant When set to true, this property enables tenants without administrative
users. Does not apply to the master tenant.
Default: false
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 REST API calls from all the sessions.
Default: false
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. Valid values are SAML and Kerberos.
See SAML/ADFS authentication details on page 891 and Kerberos
AutoReplyAddress Email address used as reply-to when no other address is provided

Default: same value as AdminEmail
CleanupMins Interval in minutes between cleanup operations on each component

Default:60
Copyright Copyright string displayed on the bottom of each page.

Default: None

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.
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.
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
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
embeddable video.
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.
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
DefaultLangCode ISO language code used by default (when no language selection is

made or available)
Default: en (English)

D2C_ConnPoolSize Specifies the number of connections to be cached and reused in order

to avoid creating new connections to the datasources in DataDirect
Cloud (D2C) frequently. The property takes values between two to
ten.
• Minimum value: 2
• Maximum value:10
Default: 5
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
DocumentationURLNewUI URL for Rollbase documentation. The Help and Learn More links open
the documentation.
Default: http://documentation.progress.com/output/rb/doc/
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
as the default as the first item in the list, for example,
ISO-8859-1,UTF-8,US-ASCII.
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
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
EnableNUIForAll Switches all tenants/customers to the new UI.

The new UI is not enabled for all tenants/customers, as this property
is not present in the shared.properties file by default. If an administrator
wants to enable the new UI for all tenants/customers, this property
must be added to the shared.properties file.
Default: false

EncryptionType Selects the default Encryption Algorithm for the environment. Default
value is 0. That is, AES-128 Symmetric Encryption Algorithm.
Note: If you upgrade to AES-256 Symmetric Encryption Algorithm,

you must install Unlimited JCE files and set the EncryptionType
value to 1.
ExpirationPolicy The number of days after which a user's password expires on the
master tenant. A value of 0 means no expiration; defaults to 10.
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
FontDirectory Directory where system fonts are stored, used by PDF Converter (see
below)
Default: None
See Configuring PD4ML on page 850 for more information.
ForumURL URL to forum page; if not set, the Rollbase Forum menu is not
available in the Rollbase menu.
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
GoogleClientId The client ID required for accessing enabled Google applications. See
Enabling Google Apps for Rollbase Private Cloud on page 828 for
information about obtaining the client ID.
GoogleClientSecretKey The secret key required for accessing enabled Google applications.
See Enabling Google Apps for Rollbase Private Cloud on page 828 for
information about obtaining the secret key.
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.
GoogleUserName The Gmail email address, for example, example@gmail.com. The

value will be ignored for SMTP and Exchange.

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
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. See the ExternalRoot entry in the
components.xml file for more information about using HTTPS.
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>

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: 20000 milliseconds

Apache.
HttpConnKeepAliveMaxReq Indicates the maximum amount of requests that can be sent on a

connection before closing it.
Default: 100 requests

Apache.
HttpConnKeepAliveTimeout Indicates the minimum amount of time an idle connection has to be

kept open (in seconds).
Default: 15 seconds
InactiveSessionExpireMins Time of user's inactivity (in minutes) before user session expires
Default: 240
IsHACluster Set to true to enable high availability. Defaults to false. See

Configuring high availability on page 914 for more information.
IsPDFAnnotationEnabled When set to true, enables the PDF annotation feature. Default value
is false.
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. Defaults to false.
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)
LinkSecurity Link to the Security Statement page on your website to be rendered

at the bottom of each page

LinkTerms Link to the Terms of Service page on your website to be rendered at

the bottom of each page
LoginSessionExpireMins Time from the user's login (in minutes) before the user session expires.
Default: 480
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.
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: None
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
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.
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: Copied from AdminEmail, which is required.
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.
• 2: If your mail server uses Transport Layer Security (TLS)
encryption.
Default: false or 0
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 765.
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.
MaxAjaxPerSession Maximum number of AJAX API calls per user login session
Default: 1000
MaxAlarmConnections The system will send a message to admin if number of database

connections exceeds this value
Default: 90
MaxAlarmThreads The system will send a message to admin if number of Java threads
exceeds this value.
Default: 200
MaxAttachmentSizeKB Maximum size of email attachment in KB

Default: 2048
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 804.
Default: 10
MaxCachedEntities Maximum number of object records cached by servers. If set to 0, no

caching is enabled.
Default: 1000
MaxChartCols Maximum number of columns displayed in charts

Default: 1000

MaxConnections Maximum number of database connections in each connection pool.

Default: 100
MaxConnLifetimeMins Maximum connection lifetime before closure (in minutes)

Default: 60
MaxDbLongStrLength Maximum size (in chars) of long text fields (CLOBs) to be stored in
the database
Default: 80000
MaxDelayedTriggers Maximum number of triggers to be executed for delayed updates

Default: 20
MaxEmailAttachments Maximum number of email attachments.

Default: 3
MaxEmailBodyKB Maximum size of email message body in KB

Default: 2048
MaxEmailQueueSize The maximum number of emails to enqueue and send asynchronously.

When the emails in the queue reach MaxEmailQueueSize, new
emails will be sent synchronously and will not be enqueued. The mail
jobs in queue will continue to be sent by another thread. As the queue
drains, and space becomes free, jobs can then be enqueued once
again. A value of 0 causes all emails to be sent synchronously.
Default: 100
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: 1000
MaxFileSizeKB Maximum size in KB for upload files.

Default: 5120
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

MaxHTTPParamLength Maximum size (in chars) of HTTP parameters processed by the system.
Default: 80000
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
MaxJSTimeMs Maximum elapsed time for the server-side JavaScript formula engine
per formula in ms (formula will be aborted afterwards).
Default: 3000
MaxListTotals Maximum number of columns with totals in views and reports

Default: 3
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
MaxQueryLength Maximum number of characters in a query sent to Query API

Default: 2000
MaxRecurrEvents Maximum number of recurrent calendar events

Default: 300
MaxReqsInQuery Maximum number of records which can be fetched by SQL query

Default: 20,000
MaxRuntimeTriggers Maximum number of triggers to be executed for non-delayed updates.

Default: 100
MaxSearches Maximum number of conditions to be used in a Detailed Search

component.
Default: 20
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.
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
MaxTimeToRunTrigMS Maximum time to run a group of triggers ON_AFTER_UPDATE etc.

Default: 30000 (30 seconds)
MaxTransactionTime Maximum time in minutes to allow a database transaction to run (will

be rolled back after that)
Default: 10
MinConnections Number of database connections initially created in each connection

pool.
Default: 1
MinExpirationPolicy
The number of days after which a user's password expires on a master
tenant. A value of 0 means no expiration; defaults to 0. Administrators
on non-master tenants control password authentication from Setup <
Authentication, see Password authentication on page 875 for more
information.
MinRecursType Minimum allowed recursion interval for triggers and batch jobs:
• 1: day (24 hours)

• 4: hour
• 5: minute 1
Default: 1
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/
ProgressDataServiceCORSHost Specifies the online address of the Progress Telerik host. This enables
Telerik applications to access Rollbase services. Defaults to
.*.(progress|icenium|telerik).com$
PurgeAfterDays Rollbase purges deleted records from the Recycle Bin after the
specified number of days
Default: 30

SecurityLevel Specifies the security level for the master tenant. See Setting and
changing security levels on page 877 for more information about security
levels.
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
embeddable video.
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
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
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
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.
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.
StatusCheck Interval in minutes between status checks on each component.

Default:5
storageUsageLimitForBkp Storage usage limit (in MB) of a full backup. For information on using
this property, see Backup and restore on page 804. Default:20
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)

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
SupportOEService Support for managing OpenEdge service objects in Rollbase. When

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.
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
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
TabularReportLayeringLimit The maximum number of layers allowed in a tabular report. Defaults

to 7.
TimeZones A comma-separated list of time zones. If required, add to this list any
TimeZone IDs which are a part of TimeZone.getAvailableIDs().
TitleTemplate The template for a page's title. Can be overridden by ISV partners.
See Creating and managing customer tenants on page 986 for more
information.
Default:{!A} | {!S} | {!P}
UnloadCustAfterMins Unloads the customer from the cache after period of time (in minutes)
Default: 60

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
VideosWebinarsURL Specifies the URL to Progress webinars and videos.

Default: https://www.progress.com/video#filter=.pm2.pp8,.pm3.pp8
embeddable video.
WebSiteHTTP HTTP URL to root of your web site

Default: http://HostName
WebSiteHTTPS HTTPS URL to root of your web site

Default: https://HostName
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.
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 10: 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.

Common options Function
-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.
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.
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.
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
-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
undeploy to see which general options are appropriate.
-u user_id:password
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.
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
reload to see which general options are appropriate.
-u user_id:password
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.
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
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
• Checking if an instance is running. Output is 0 if it is not running.
• Using the output (which is easily parseable) 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.)
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
tomcat:tomcat.)

-f
Return full status information.
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"
<memorypool name="PS Survivor Space" type="Heap memory" usageInit="8388608"
<memorypool name="Code Cache" type="Non-heap memory" usageInit="2555904"
<memorypool name="PS Perm Gen" type="Non-heap memory" usageInit="67108864"
</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.
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
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
Syntax
tcman.sh enable [general_options] -u user_id:password app_name
Parameters
general_options
start to see which general options are appropriate.
-u user_id:password
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
Stop a Web application (disable)
Purpose
Stop a running Web application.
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
-u user_id:password
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.
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.
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.
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
tomcat:tomcat.)
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

–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.
–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.
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
-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.
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
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
Architecture: amd64
...
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
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
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.
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]
Parameters
general_options
Specify one or more of the general TCMAN options. Run tcman.sh help clean to see which
-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.
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.
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.
• 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]
Parameters
general_options
Specify one or more of the general TCMAN options. Run tcman.sh help start to see which
-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
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.
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
-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
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
• 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
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 CLASSPATH:
/psc/pashome/bin/bootstrap.jar:/users/doc/agarbacz/psc/pashome/bin/tomcat-juli.jar
Server version: Apache Tomcat/7.0.42
Server built: Jul 2 2013 08:57:41
Server number: 7.0.42.0
OS Name: Linux
Architecture: amd64
JVM Vendor: Oracle Corporation
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

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

. . .
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.
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
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
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.
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:

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 12: worker.properties
example on page 972.)
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.
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
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 11: 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)
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 12: 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.
• 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
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.
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.
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:
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: -

13
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.

Chapter 13: 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.
• 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.

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

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>

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)

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 file. For more information on shared.properties file and its properties,
see shared.properties on page 926.
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.

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.

• 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.

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 978.
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.

Use sandbox customer tenants to develop and test your applications. Then use the XML publishing mechanism
described in Publishing and distributing applications on page 765 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 861 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.

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 Application Directory/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 Application Directory/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 Application Directory on page 291.
• 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 293.

Version history and rolling back

When an application publisher uploads a new version of a published application to the Application Directory
or 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.

14
Reference
Topics in this section describe Rollbase APIs, built-in CSSs, and field types.
• Server-side API
• Client-side AJAX API
• Client-side JavaScript
• Code Generator
• Metadata API and XML Reference
• Rollbase REST Methods
• Rollbase SOAP Methods
• Rollbase CSS Styles for the Classic UI
• Field types
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.

Chapter 14: 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 719.
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.

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.

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);

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:


Server-side API
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 926 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).
• 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
• 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
Syntax
rbv_api.selectQuery (query, maxRows, arg1, arg2…)
Parameters
query
SQL SELECT query. See Query API on page 990 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]+",
"+arr[i][2] +", "+arr[i][3]+"<br>";
}
return buff;

Server-side API
rbv_api.selectQuery2()
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.
all columns.
Syntax
rbv_api.selectQuery2 (query, rowFrom, maxRows, arg1, arg2…)
Parameters
query
rowFrom
Number of row to start output (0 based)

maxRows
args
Return value
Query result in a 2-D array
rbv_api.selectValue()
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.
all columns.

Server-side API
Syntax
rbv_api.selectValue (query, arg1, arg2…)
Parameters
query
SQL SELECT query. See examples below and see Query API on page 990 for limitations.
args
Return value
Query result as a single value
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()
Purpose
Runs a SQL SELECT query and returns a single decimal value. It is similar to the selectValue() method.

all columns.
Syntax
rbv_api.selectNumber (query, arg1, arg2…)
Parameters
query
SQL SELECT query. See examples below and see Query API on page 990 for limitations.
args
Return value
Query result as a decimal number
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");

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.
Syntax
rbv_api.selectCustomerQuery (custId, query, rowFrom, maxRows, arg1, arg2…)
Parameters
custId
ID of the customer record to query
query
rowFrom
maxRows
args
Return value
Query results as a 2-D array
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 859 for more information about customer tenants and the master
server.

rbv_api.selectCustomerValue()
Purpose
Similar to selectValue() returns a single value, but is called from the master server and runs on the customer
with the specified ID..
Syntax
rbv_api.selectCustomerValue (custId, query, arg1, arg2…)
Parameters
custId
query
args
Return value
Query result as a single value
type.
server.
rbv_api.selectCustomerNumber()
Purpose
Same as selectNumber(), but is called from the master server and runs on the customer tenant with the
specified ID.

Server-side API
Syntax
rbv_api.selectCustomerNumber (custId, query, arg1, arg2…)
Parameters
custId
query
SQL SELECT query. See an example below and see Query API on page 990 for examples and
limitations.
args
Return value
Query result as a number
type.
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.getCount()
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
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");
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 1005.
Syntax
rbv_api.getRelatedIds (relName, id)
Parameters
relName
Integration name of relationship
id
Record ID from one side of the relationship
Return value
An array of related record IDs

Server-side API
Example
var arr = rbv_api.getRelatedIds("R1321", {!id});
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 1004.
Syntax
rbv_api.getRelatedIds2(relName, objName, objId)
Parameters
relName
Integration name of the relationship.
ObjName
Integration name of the object.
objId
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.getRelatedFields()
Purpose
For native Rollbase objects, returns an array of field values from related records for a given relationship and
Object ID.
a D2C connection), you can use the method, rbv_api.getRelatedFields2() on page 1006.

Syntax
rbv_api.getRelatedFields(relName, id, fieldName)
Parameters
relName
Integration name of relationship
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.
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
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 1005.
Syntax
rbv_api.getRelatedFields2(relName, objName, objId, fieldName)
Parameters
relName
Integration name of relationship.
objName
Integration name of Object.

Server-side API
objId
Record ID from one side of the relationship.
fieldName
Integration name for field in related object.
Return value
Array of field values from related records or NULL if no related records exist.
Example
var values = rbv_api.getRelatedFields2("R1321", "ex_group", "{!#UID}", "status");
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()
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.
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.
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, objId, fieldName)
Parameters
objName
Integration name of object
objId
ID of object record
fieldName
Integration name of field to retrieve value from

Server-side API
Return value
Value of requested field
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()
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.
Syntax
rbv_api.getNumFieldValue(objName, objId, fieldName)
Parameters
Parameter Description
objName Integration name of object
objId ID of object record
fieldName Integration name of field
Return value
Value of requested field

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.
Syntax
rbv_api.getBinaryData(objName, objId, fieldName)
Parameters
fieldName integration name of file upload field to retrieve value

from
Return value
A base-64 encoded string or null
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.
Syntax
rbv_api.getTextData(objName, objId, fieldName)
Parameters

Server-side API
fieldName integration name of File Upload field to retrieve value

from
Return value
A plain-text string or Null
rbv_api.isFieldEmpty()
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.
Syntax
rbv_api.isFieldEmpty(objName, objId, fieldName)
Parameters
objName
objId
ID of object 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()
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.
Syntax
rbv_api.setFieldValue(objName, objId, fieldname, newValue)
Parameters
objName
objId
ID of object record
fieldName
Integration name of field to set value in
newValue
Value to be set
Return value
None

Server-side API
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
only works with native Rollbase objects.
Syntax
rbv_api.setBinaryFieldValue(objName, objId, fieldname, encodedValue, contentType,
fileName)
Parameters
objName
objId
ID of object 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

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.
Syntax
rbv_api.setTextFieldValue(objName, objId, fieldname, textValue, contentType,
fileName)
Parameters
objName
objId
ID of object 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
Example
var xmlBody = "<test>TEST</test>"
rbv_api.setTextFieldValue("invoice", {!id}, "xmlField", xmlBody,
"text/xml", "invoice.xml");

Server-side API
rbv_api.createRecord()
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.
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
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()
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().
Syntax
rbv_api.updateRecord(objName, objId, arr)
Parameters
objName
The object integration name.
objId
The ID of the object record.
arr
Return value
None

Server-side API
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()
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().
Syntax
rbv_api.cloneRecord(objName, objID, arr)
Parameters
objName
Integration name of the type of object to create
objID
ID of the record to clone
arr
Return value
Object ID of the newly created record
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()
Purpose
This Object Script method creates a relationship between two records and returns true if a new relationship
has been successfully created.
Syntax
rbv_api.attach(relName, objName1, objId1, objName2, objId2)
Parameters
relName
Integration name of the relationship
objName1
Integration name of the first object
objId1
ID of the first Object record
objName2
Integration name of the second object
objId2
ID of the second object record
Return value
true, if association succeeded

Server-side API
rbv_api.detach()
Purpose
This Object Script method removes a relationship between two records.
Syntax
rbv_api.detach(relName, objName1, objId1, objName2, objId2)
Parameters
relName
Integration name of the relationship
objName1
Integration name of the first object
objId1
ID of the first Object record
objName2
Integration name of the second object
objId2
ID of the second object record
Return value
None

rbv_api.runTrigger()
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.
Syntax
rbv_api.runTrigger(objName, objId, triggerOrigId, checkValidation, runRecursions)
Parameters
objName
Integration name of the object
objId
ID of the record on which to run the trigger
triggerOrigId
Integration name (string) or original ID (string) of the trigger
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
Example
rbv_api.runTrigger("Query", {!id}, "TaC4hpbwSDmjSPOHavRqJA", false, true);

Server-side API
rbv_api.deleteRecord()
Purpose
This Object Script method deletes the specified record.
Syntax
rbv_api.deleteRecord(objName, objId)
Parameters
objName
objId
ID of record to delete
Return value
None
Delete permission for the selected object type.
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
Syntax
rbv_api.setCreator(objName, objId, creatorName, creatorId)

Parameters
objName
objId
creatorName
Integration name of the user or portal user to be set as creator
creatorId
ID of the creator record
Return value
None
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 423 for
more information about the approval process.
Syntax
rbv_api.startApproval(objName, objId, actionId)
Parameters
objName
objId
actionId
The original ID of the workflow action that started the approval process (can be found on the workflow
action's view page).

Server-side API
Return value
None.
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, objId, userId)
Parameters
objName
objId
ID of the object 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, objId, userId, isViewed)
Parameters
objName
objId
ID of object 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, objId, userId)
Parameters
objName
objId
ID of object record
userId
ID of the user who might have flagged the record
Return value
true if a record was flagged

Server-side API
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, objId, userId, isFlagged)
Parameters
objName
objId
ID of object record
userId
ID of the user who might have flagged the record
isFlagged
true or false
Return value
None
rbv_api.getSelectedIds()
Purpose
Gets an array of record ids selected by current user using check boxes in list view.
Syntax
rbv_api.getSelectedIds(objName)
Parameters
objName
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()
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.
rbv_api.getIdByCode()
Purpose
Returns the ID of a status or a picklist item with the given integration code.
Syntax
rbv_api.getIdByCode (objName, fieldName, code)

Server-side API
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()
Purpose
Returns the code of a status or a picklist item with the given ID.
Syntax
rbv_api.getCodeById(objName, fieldName, id)
Parameters
objName
fieldName
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
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)

Server-side API
Parameters
objName
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);
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)
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()

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
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});
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.

Server-side API
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, ObjId, templateId)
Parameters
objName
The object Integration name.
objId
ID of object record.
templateId
The original ID of the document template.
Return value
The template as a base-64 encoded String.
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()
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);

Server-side API
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.
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
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

Server-side API
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, ",", ".");
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)
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, ".", " ");
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)
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

Server-side API
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
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.
rbv_api.getPDFProperty()
Purpose
Returns the specified property of the PDF document specified as a base-64 encoded string. This method only
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
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)

Server-side API
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).
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)
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.
Return value
HTTP response
Example
var headers = {"Content-Type": "application/xml"};
var info =
rbv_api.sendHttpGet("http://www.rollbase.com/master/system/ri.jsp",headers,"ISO-8859-1");
rbv_api.println(info);
Output:
4.08|2013-06-01T
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)
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.
Return value
Body of HTTP response

Server-side API
Example
The following example logs in to a remote server:
var url = "http//my_server/login?loginName="my_name"&custId=123123";

var params = {"password":"my_password"};
var resp = rbv_api.sendHttpPost(url, params, null);
rbv_api.println(resp);
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)
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
Return value
Body of HTTP response

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
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)
Parameters
name
Name of input HTML box of a UI form HTML element
Return value
HTTP parameter or null
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.

Server-side API
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);
}
}
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.
Syntax
rbv_api.jsonToString(json)
Parameters
json
A JSON object
Return value
A text string

Server-side API
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 800.
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");
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.

Server-side API
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.
Syntax
rbv_api.isPortal()
Parameters
None
N/A
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.
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.
Syntax
rbv_api.isAPI()
Parameters
None
N/A
Return value
true or false
rbv_api.isDelayed()
Purpose
Returns true if this trigger is delayed and running when no user is logged in.

Server-side API
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.
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.
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.
Syntax
rbv_api.isUpdate()
Parameters
None
N/A
Return value
true or false
Example
rbv_api.isDelete()
Purpose
Returns true if trigger is called while deleting an existing record.
Syntax
rbv_api.isDelete()
Parameters
None
N/A

Server-side API
Return value
true or false
Example
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

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

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()

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, objId, text)

Server-side API
Parameters
objName
objId
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);

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, "address@gmail.com", 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.

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, "address@mydomain.com", 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
var x = rbv_api.getMailMessageCount();
rbv_api.closeMailSession();

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
var m = rbv_api.getMailMessage(100);
var x = m.get("subject");
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)

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 1058.
Example
var arr = rbv_api.getMailMessages(100, 110);
var m = arr[k];
rbv_api.println(m.get('subject'));
}
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 1144 for information about client-side user session data APIs.

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
1059 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);

} catch (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);

} catch (error) {

Server-side API
}
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
1059 for more information about user session data.
Syntax
rbv_api.getSessionData(key);
Parameters
key
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));
} catch (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.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 1059 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());
} catch (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 1059 for more information about user session data.
Syntax
rbv_api.removeSessionData(key);

Server-side API
Parameters
key
Return value
If successful, returns the string OK. If unsuccessful, throws an exception with one of the following messages:
• 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);
} catch (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 1059 for
more information about user session data.
Syntax
rbv_api.removeAllSessionData();
Parameters
None
Return value
If successful, returns the string OK.

Example
If successful, the following example removes all user session data and returns the string OK.
try {
var resp = rbv_api.removeAllSessionData();
} catch (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 719.
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 989).
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 617.
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.

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
rbf_createRecord()
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
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

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.
rbf_deleteRecord()
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.
rbf_getCount()
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
rbf_getCount2()
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)
Parameters
viewId
The original ID of the view
filterName
The integration name of the field to filter output using “equals” (replaces the filter set in the view, if
any).
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.
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_getViewCount
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": {
"dateFilters": [{
"field": "<integration_name_of_field>",
"value": "<valid_date_filter_operand>"
}],
"filters": [{
"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.
See rbf_getViewPage on page 1073 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",
}],
"filters": [
{
"field": "amount",
"value": "1606",
"opCode": "GE"
},
{
"field": "price",
"value": "102",
"opCode": "EQ"
}
],
"joinType": "OR"
}
});
rbf_getFields()
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. 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.
Syntax
rbf_getFields(objName, id, fields, callback, useLegacyDateFormat, options)

Parameters
objName
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
as a String.
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"}.
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()
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
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
as a String.
options

Example
The following example fetches set or rows and processes results in a loop:
function my_callback(arr) {
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()
Purpose
Similar to rbf_getPage() on page 1070, 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.
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
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)
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
useLegacyDateFormat
as a String.
options
rbf_getViewPage
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.
it will throw an error.

Syntax
rbf_getViewPage(viewId, callback, options);
Parameters
viewId
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).
• 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": {
"dateFilter": [{
"value": "<valid_date_filter_operand>"
}],
"filters": [{
"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": [{
"order": "asc(default)|desc"
}, {
}, {
}]
• langCode: A valid two-letter ISO language code, for example, {"langCode":"es"}.

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.
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 13: 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

Date Filter Value: UI Date Filter Value: API
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
Next 30 days TODAY+1|TODAY+30
The following table lists the different values that an opCode key can take for field types derived from UI.
Table 14: 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

opCode Key Value
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
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
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",
}],
"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"
});
rbf_getRelatedFields()
Purpose
Warning: This function is deprecated. Use rbf_getRelatedFields2() on page 1079.
For native Rollbase objects, this function retrieves the values of selected field for records related for a selected
Rollbase record.
The current user must have View permission on the selected object(s) to run this API.
Syntax
rbf_getRelatedFields(relName, id, fieldName, callback)
Parameters
relName
The integration name of selected Relationship 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).
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_getRelatedFields("R12345", id, "amount ", my_callback);
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.
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
as a String.
options
Example
The following example reads field "amount" from related records and makes these values available for
computations:
// 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.
a D2C connection), you can use the method, rbf_getRelatedIds2() on page 1081.
Syntax
rbf_getRelatedIds(relName, id, callback)
Parameters
relName
Integration name of selected Relationship definition
id
ID of selected Object record

callback
A callback function that will receive parameters: relName, id, an array of related ids.
rbf_getRelatedIds2()
Purpose
connection), this function retrieves the ids of records related to a selected Rollbase record.
Note: For native Rollbase objects, you can use the method, rbf_getRelatedIds() on page 1080.
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.
Example
// Do something...
}
}
rbf_getRelatedIds2("R12345", "obj1", id, my_callback);
rbf_runTrigger()

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 list of name-value pairs set in a variable in the form {name1 : value1 , name2 :
value2}. When the key runRecursions is set to true, configures trigger to run recursively,
assuming recursive properties are set on the trigger definition page. Default value is false.
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()
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.
all columns.
Syntax
rbf_selectNumber(query, callback)

Parameters
query
SQL SELECT query.
callback
A callback function that will receive a single value returned by the query.
rbf_selectQuery()
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.
all columns.

Syntax
rbf_selectQuery(query, maxRows, callback, useLegacyDateFormat, options);
Parameters
query
SQL SELECT query. See Query API section below for examples and limitations.
maxRows
callback
A callback function that will receive a 2D JSON array with query results as parameter.
useLegacyDateFormat
as a String.
options
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()

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 1084 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.
all columns.
Syntax
rbf_selectQuery(query, rowFrom, maxRows, callback, useLegacyDateFormat, options);
Parameters
query
SQL SELECT query. See Query API section below for examples and limitations.
rowFrom
maxRows

callback
A callback function that will receive a 2D JSON array with query results as parameter.
useLegacyDateFormat
as a String.
options
Example
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, my_callback,

true, {"langCode":"fr"});
rbf_selectValue()
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.
all columns.


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
as a String.
options
Example
function my_callback(returnAmt) {
// Do something...
}
rbf_selectValue("select amount from order where id={!id}", 1, my_callback,

true,{"langCode":"fr"} );
rbf_setField()

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.
Syntax
rbf_setField(objName, id, fieldName, fieldValue, useIds, callback,
useLegacyDateFormat)
Parameters
objName
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
useLegacyDateFormat
as a String.

rbf_updateRecord()
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.
Syntax
rbf_updateRecord(objName, id, fieldMap, useIds, callback, useLegacyDateFormat)
Parameters
objName
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
callback
useLegacyDateFormat
as a String.

Field Manipulation
The functions in this section allow you to access and modify record fields.
rbf_getFieldContent()
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
rbf_getFieldValue()
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
Example
The following example returns the Spanish value of the field with the integration name name.
rbf_getFieldValue("name",{"langCode":"es"});
rbf_getPicklistCode()
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
rbf_getPicklistCodes()
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

rbf_setFieldContent()
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
value
The new value to set
rbf_setFieldValue()
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
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()
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
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.

rbf_setPicklistCode()
Purpose
This function sets the value of a picklist field or radio buttons if the code attribute of the particular option is
equal to the optCode parameter. It will also invoke onchange (onclick) event handling code associated
with this field.
Syntax
rbf_setPicklistCode(fieldName, optCode)
Parameters
fieldName
optCode
This value will be compared to the integration code of a particular picklist option
Data Formatting
The methods in this section allow you to manipulate numbers, dates, and currency.
rbf_getDate()
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

rbf_getDigits()
Purpose
Extracts digits from string value and ignores all other characters.
Syntax
rbf_getDigits(value)
Parameters
value
The string from which to extract digits
rbf_getFloat()
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
rbf_formatCurrency()
Purpose
Formats a given number into a currency string.

Syntax
rbf_formatCurrency(value, currSymbol, showZero, decPlaces, thsSep)
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)
rbf_formatDate()
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 1157 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.

Example
This example uses the PageLocalization object to populate the format parameter:
rbf_formatDate(new Date(), rbf_getPageContext().getPageLocalization().getDateFormat());
rbf_formatNumber()
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).
Example
var x = rbf_formatNumber(7000123.45,4,'.',',');
Result: 7,000,123.4500
rbf_formatUsingMask()

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
Example
var x = rbf_formatUsingMask("123456789", "###-##-####");
Result: 123-45-6789
rbf_getInt()
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
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 511 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:

The following topics provide examples and document the grid control API:
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.

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 512 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.

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 1101. 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 1101 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));
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 t = a*p;
rbf_setGridContent2(0, 'total', rowIndex, rbf_formatCurrency(t));
}

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()
Purpose
Adds a new empty row to a grid.
Syntax
rbf_addGridRow(gridNo)
Parameters
gridNo
The 0-based number of Grid Control on page
rbf_delGridRow()
Purpose
Deletes the row with given index from a grid.
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.
rbf_getGridControlComponent()
Purpose
Returns the GridControl on page 1152 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 1134.
Note: This API and the GridControl on page 1152 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.
Return value
The specified GridControl on page 1152 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();
rbf_getGridFieldContext()
Purpose
Returns the GridFieldContext on page 1153 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
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()
Purpose
Gets the name of the field that was last changed in the Grid.
Syntax
rbf_getGridField(gridNo)
Parameters
Parameter
Description
gridNo

rbf_getGridPicklistCode()
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
fieldName
The integration name of the input field
rowIndex
Return Value
The integration code of the grid control picklist field. Null if the grid control does not exist on the page.
rbf_getGridValue2()
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
fieldName
rowIndex
rbf_getMaxRowIndex2()
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)
Parameters
gridNo
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()

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
fieldName
The integration name of formula or template field
rowIndex
value
The HTML content to be assigned to the cell
rbf_setGridPicklistCode()
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 1095.
Syntax
rbf_setGridPicklistCode(gridNo, fieldName, rowIndex, optCode)
Parameters
gridNo
fieldName

rowIndex
optCode
Value will be compared to the integration code of a particular picklist option
rbf_setGridValue2()
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)
Parameters
gridNo
fieldName
rowIndex
The row number. Row number start with 0.
value
HTML content to set in field
rbf_showGridTotals()
Purpose
Calculate and display totals for grid.

Syntax
rbf_showGridTotals(gridNo)
Parameters
gridNo
rbf_sumGridColumn2()
Purpose
Retrieves the sum of column values in a grid.
Syntax
rbf_sumGridColumn2(gridNo, fieldName)
Parameters
gridNo
fieldName
The integration name of formula or numeric input field
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 1173.
rbf_createApplicationDef()
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
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 ref_setErrorsCallback(callback) is
invoked to receive the error message.
For information about the XML elements in an Application, see Application XML Elements on page 1173.
rbf_createFieldDef()

Purpose
Creates a field definition from an XML document.
Syntax
rbf_createFieldDef(xmlString, callback, errorCallback)
Parameters
xmlString
A string containing the XML document describing the field to be created.
callback
argument.
errorCallback
For information about the XML definitions in a field, see Field XML Definition on page 1180.
rbf_createObjectDef()
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
argument.

errorCallback
For information about the XML definitions in an object, see Object XML Definition on page 1176.
rbf_createRelationshipDef()
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
argument.
errorCallback
For information about the XML definitions in a relationship, see Relationship XML Definition on page 1187.
rbf_deleteApplicationDef()
Purpose
Deletes an application definition and all of its component definitions.

Syntax
rbf_deleteApplicationDef(appId, callback, errorCallback)
Parameters
appId
The original application ID.
callback
argument.
errorCallback
rbf_deleteFieldDef()
Purpose
Deletes a field definition from the specified object.
Syntax
rbf_deleteFieldDef(objName, fieldName, callback, errorCallback)
Parameters
objName
fieldName
callback
argument.

errorCallback
rbf_deleteObjectDef()
Purpose
Deletes an object definition, including its fields and relationships.
Syntax
rbf_deleteObjectDef(objName, callback, errorCallback)
Parameters
objName
callback
argument.
errorCallback
rbf_deleteRelationshipDef()
Purpose
Deletes a relationship definition.

Syntax
rbf_deleteRelationshipDef(relName, callback, errorCallback)
Parameters
relName
The relationship integration name.
callback
argument.
errorCallback
rbf_getApplicationDef()
Purpose
Retrieves an XML description of a Rollbase application.
Syntax
rbf_getApplicationDef(appId,callback,errorCallback)
Parameters
appId
The original application ID.
callback
argument.
errorCallback

For information about the XML elements in an application, see Application XML Elements on page 1173.
rbf_getFieldDef()
Purpose
Retrieves a field definition as an XML document.
Syntax
rbf_getFieldDef(objname, fieldName, callback, errorCallback)
Parameters
objName
fieldName
callback
argument.
errorCallback
rbf_getObjectDef()
Purpose
Retrieves the specified object definition and returns it as an XML document.

Syntax
rbf_getObjectDef(objName, callback, errorCallback)
Parameters
objName
callback
argument.
errorCallback
rbf_getRelationshipDef()
Purpose
Retrieves a relationship definition as an XML document.
Syntax
rbf_getRelationshipDef(relName, callback, errorCallback)
Parameters
relName
callback
argument.

errorCallback
rbf_updateApplicationDef()
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.
callback
argument.
errorCallback
rbf_updateFieldDef()
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
argument.
errorCallback
rbf_updateObjectDef()
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
argument.

errorCallback
rbf_updateRelationshipDef()
Purpose
Updates a relationship definition from an XML document.
Syntax
rbf_updateRelationshipDef(xmlString, callback, errorCallback)
Parameters
xmlString
A string containing the XML document describing the relationship to be updated.
callback
argument.
errorCallback
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.

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 584 and Managing object pages on page 492 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.
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()
Purpose
Returns the integration code of a picklist item, status, or template with the given ID.
Syntax
rbf_getCodeById(objName, fieldName, id, callback)

Parameters
objName
The object definition integration name
fieldName
The integration name of picklist field
id
ID of picklist item
callback
The callback function that will receive code of picklist item as first parameter (null if not found).
rbf_getExchangeRate()
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)
Example
rbf_getExchangeRate("EUR", "USD", null, function(rate) { alert("EUR/USD="+rate); });

rbf_getIdByCode()
Purpose
Returns the ID of a picklist item, status, or template with the given code.
Syntax
rbf_getIdByCode(objName, fieldName, code, callback)
Parameters
objName
Object definition integration name
fieldName
The integration name of picklist field
code
The integration name of picklist item
callback
The callback function that will receive the ID of picklist item as first parameter (-1 if not found).
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
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).
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.
Syntax
rbf_getPicklist(objName, fieldName, mainValueId, callback, options)
Parameters
objName
fieldName
mainValueId
callback
The callback function that will receive a JSON array of picklist items as its first parameter.
options
rbf_isChecked()
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
rbf_isEmpty()
Purpose
Returns true if argument is null or empty string.
Syntax
rbf_isEmpty(arg)
Parameters
arg
The argument to be tested
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()
Purpose
Returns true if record with given id is selected (check box checked) in list view.
Syntax
rbf_isSelected(recordId)

Parameters
Parameter
Description
recordId
The numeric ID of record
rbf_isZero()
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.
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()
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
rbf_setErrorsCallback()
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
Example
};
rbf_setLookupFilter()

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);
Parameters
fieldName
Integration name of the lookup field
filterName
Name of the related object field used for filtering
filterValue
Value of fields to display
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()
Purpose
Selects/deselects record with given ID in list view.
Syntax
rbf_setSelected(recordId, selected)
Parameters
Parameter
Description

recordId
The numeric ID of record
selected
true or false
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.
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 1132. 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.
Permissions
It is only available for Administrative users.
Example
rbf_startServerDebugging(function() {
alert("Start debugging server-side API"); });
Display Functions
The Rollbase JavaScript API functions in this section can be useful in customizing UI presentation of Rollbase
pages.
rbf_activatePageTab()
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

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 1151 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
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 1155 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).

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 1156 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
Return value
The PageContext on page 1156 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()
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

rbf_getViewSelector()
Purpose
This function returns the view ID used by a lookup field for both auto-complete and pop-up selectors.
Syntax
rbf_getViewSelector(fieldName)
Parameters
fieldName
The integration name of lookup field
rbf_growl()
Purpose
Displays a growl-type floating notification in the upper right side of the screen.
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.

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.
Syntax
rbf_growlError(title, message);
Parameters
title
message
rbf_hideGrowl()
Purpose
Hides a notification if one is being displayed.
Syntax
rbf_hideGrowl();
rbf_hideInfoMessage()

Purpose
This function hides the status message at the top of the page. This method implementation calls rbf_hideGrowl()
on page 1137.
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.
Syntax
rbf_growlInfo(title, message);
Parameters
title
message
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.
Syntax
rbf_growlSuccess(title, message);

Parameters
title
message
Return Value
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.
Syntax
rbf_growlWarning(title, message);
Parameters
title
message
rbf_showInfoMessage()

Purpose
Displays a status message on the top of the page, which will automatically disappear after 40 seconds. This
method implementation calls rbf_growlInfo() on page 1138
Syntax
rbf_showInfoMessage(message, isError)
Parameters
message
The message text
isError
Value of true if message represents an error (errors are shown in dark red text rather than black)
rbf_showMessage()
Purpose
Displays a status message on the top of the page, which will automatically disappear after 40 seconds. This
method implementation calls rbf_growl() on page 1136.
Syntax
rbf_showMsg (message, type);
Parameters
message
The message to display.
type
The message type, one of: success, info, warn, or error
Return Value
?
Example
Introduce example here.
?

rbf_showOrHideField()
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
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.
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:
rbf_showOrHidePageTab()
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

rbf_showOrHideSection()
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 1135.
Syntax
rbf_showOrHideSection(sectionId, showSection)
Parameters
sectionId
The original ID of page's section (can be found in Page Editor)
showSection
If true, show section, if false, hide section
rbf_setSectionCollapse()
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
rbf_setViewSelector()
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.
Syntax
rbf_setViewSelector(fieldName, selectorViewId)
Parameters
fieldName
The integration name of lookup field
selectorViewId
ID of view to use
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 1059 for information about server-side user session data APIs.

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 1146 and removed using the function
rbf_removeSessionData() on page 1148. 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 1130 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
error.
Syntax
rbf_setSessionData(key, value, callback);
Parameters
key
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.
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 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 handleSessionData = function (response) {
if(console){
console.log("Response is: ", response);
}
}
rbf_setSessionData();
</script>
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 1144 for more information about custom user session data.
• No Mappings Set for [key] — There is no value associated with the specified key or there is no
custom session data to retrieve
error.
Syntax
rbf_getSessionData(key, callback);

Parameters
key
callback
Return value
If successful, passes the value associated with that key (JavaScript primitive) to callback function and sets
the HTTP status to 200
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 handleSessionData = function (dataValue) {
if(console){
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 1144 for more information about custom user
session data.
via rbf_setErrorsCallback() on page 1130 and passes that function the following message:
• No Custom Session Data is Set by User — No custom session data exists for the user

error.
Syntax
rbf_getAllSessionData(callback);
Parameters
callback
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 handleSessionData = function (dataValue) {
if(console){
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.
• No Mappings Set for [key] — There is no value associated with the specified key

error.
Syntax
rbf_removeSessionData(key, callback);
Parameters
key
A string that is the key for a key/value pair of stored custom session data
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.
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 handleSessionData = function (returnValue) {
if(console){
console.log("Response is " +returnValue);
}
}
rbf_removeSessionData("name1", handleSessionData);
</script>
rbf_removeAllSessionData()
Purpose
This function removes all session data for the user.
via rbf_setErrorsCallback() on page 1130 and passes that function the following message:
• No Custom Session Data is Set by User — No session data exists for the user
error.

Syntax
rbf_removeAllSessionData(callback);
Parameters
callback
Return value
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 handleSessionData = function (returnValue) {
if(console){
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 349 for information about where you can use
client-side scripts. See Programmatic client-side customization on page 580 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.
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:
try {

if ( window.rb !== undefined && window.rb.newui !== undefined ) {

console.log("*** Executing Custom Sidebar for New UI");
}
}
catch (e) {alert ('Error in custom sidebar code' + e);
}
</script>
Debugging scripts
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:
try {
if ( window.rb !== undefined && window.rb.newui !== undefined ) {
debugger; // set breakpoint
}
}
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.
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 1134.
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
• 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
• 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 1154 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
• 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 1105. The interface
of GridFieldContext includes all functions defined for FieldContext on page 1151. See rbf_getGridFieldContext()
on page 1105 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.
• getGridRow() — Returns the GridRow on page 1154 object for the associated field.
• getGridFieldData() — Returns a JSON object representing the value of the associated field.
• getGridComponent() — Returns the GridControl on page 1152 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 1152 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 1151 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 1134 to access a specific PageComponent.
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 1135.
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
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 1158 object
• hasSessionExpired() — Returns true if the user session has expired, otherwise returns false.
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 1168 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 1156 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.
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 1156 function getPageToolbar() to access the
PageToolbar object.
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);
Functions
The functions described in this section can be run in client-side scripts.

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 1169 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
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.
<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>
isMobile()
Purpose
Detects whether Rollbase is running on a mobile device (tablet or smart phone).
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.
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.

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.
Syntax
rb.newui.util.removeFieldLabel(fieldName)
Parameters
fieldName
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
ajaxNavigation 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.
You must set this property's value in a custom sidebar script that executes before the UI starts. See Executing
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:
if(rbf_isNewUI()){
rb.newui.options.applicationPage.ajaxNavigation = false;
}
</script>
ajaxNavigation for tabs
Purpose
This property allows you to specify whether Rollbase uses AJAX requests to navigate between top-level tabs.
Setting it to false disables navigation between top-level tabs using AJAX requests. Setting it to true enables
navigation between top-level tabs using AJAX requests.


rb.newui.options.tabMenuLink.ajaxNavigation
Example
The following example disables navigation between top-level tabs using AJAX requests for an application:
if(rbf_isNewUI()){
rb.newui.options.tabMenuLink.ajaxNavigation = false;
}
</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.
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:
When used in conjunction with showBooleanOperators on page 1164, 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.

rb.newui.options.filters.showAdvancedFilterTypes
Example
The following code hides the advanced filter options component.
</script>
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.
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 1163, and both are set to false, the entire
row in which they appear is hidden, saving vertical space on the screen:

rb.newui.options.filters.showBooleanOperators
Example
The following code hides the Boolean operator component.
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.
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:
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:

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.

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 )

{
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.

rb.newui.options.objectViewPage.recordNavigationAjax

Example
The following example disables navigation between object records using AJAX requests for an application:
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.

rb.newui.options.useResponsiveImage
Example
The following script turns off responsive images:
if(rbf_isNewUI()){
rb.newui.options.useResponsiveImage = false;
}
</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 1159
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 1159 for an example.
See HTML and Script components on page 351 for more information about script components.
• 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 1152 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 1152 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 1152 for more information.
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){

Code Generator
console.log("**** Processing event rbs_notificationDisplayed ****");

console.log("Type: "+ data.type);
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>
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 Administration 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
{!#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.

Template Token Description
{!#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.
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 on page 1173

• SOAP Metadata Methods on page 1190
• REST Metadata Methods on page 1203
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 1173

• Object XML Definition on page 1176
• Field XML Definition on page 1180
• Relationship XML Definition on page 1187
Application XML Elements

The following sections describe the application-level XML elements that define application metadata:
• Application Node on page 1173

• ApplicationProps Node on page 1174
• Application Definition XML Example on page 1175
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.
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.
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>

</DataObjectDefs>
</Application>

Object XML Definition

The following nodes and elements describe an object definition:
• DataObjectDef Node on page 1176

• ObjectProps Node on page 1177
• Object Definition XML Example on page 1179
DataObjectDef Node
The following table describes the DataObjectDef XML node.
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
fieldGroups.xml file for
attribute names.
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.
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.
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.
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.
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>
Field XML Definition

The following topics describe the XML elements that describe a field:
• DataFieldDef Node on page 1180

• FieldProps Node on page 1183
• Field Definition Example on page 1186
• ListItem Node on page 1186
• List XML example on page 1187
DataFieldDef Node
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 FieldProps Node on
page 1183 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.
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.
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.

FieldProps Node
The following table describes elements of a FieldProps node:
autoNumFormat Node String For AutoNum fields, the

format. For example, PO#
{YYYY}-{0000000} will
be converted to a value
such as PO#
2007-0000001
autoNumStart Node String For AutoNum fields, the

number from which to
start.
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.
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.
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.
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>
<isUnique>true</isUnique>
</Props>
</DataFieldDef>
ListItem Node
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 1187

• Example of a relationship definition on page 1189
RelationshipDef Node
The following table describes the child elements of a RelationshipDef node:
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

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,

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.
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.
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 1173 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.
Output
Status text:
Application ABC has been created
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 1176 for a description of the DataObjectDef XML node and an example
of its use.
Syntax
createObjectDef(string sessionId, string xmlString)
Parameters
sessionId
xmlString
An XML string describing the object in an DataObjectDef node, along with fields and relationships.
Output
Status text: Object ABC has been created
Example
This example shows how to call createObjectDef():
String infoMessage = binding.createObjectDef(sessionId, xmlString);
createFieldDef()
Purpose
Creates a new field definition from an XML document.
See Field XML Definition on page 1180 for a description of the DataFieldDef XML node and an example of
its use.
Syntax
createFieldDef(string sessionId, string xmlString)

Parameters
sessionId
xmlString
An XML string describing the field in an DataFieldDef node.
Output
Status text: Field ABC has been created
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 1187 for a description of the RelationshipDef XML node and an
example of its use.
Syntax
createRelationshipDef(string sessionId, string xmlString);
Parameters
sessionId
xmlString
An XML string describing the field in an RelationshipDef node.
Output
Status text: Relationship R123456 has been created

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.
of its use.
Syntax
deleteApplicationDef(string sessionId, string appId);
Parameters
sessionId
appId
The original ID of the application to retrieve.
Output
Status text:
Application ABC has been deleted
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.
its use.
Syntax
deleteFieldDef(string sessionId, string objDefName, string fieldName);
Parameters
sessionId
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
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.
of its use.
Syntax
deleteObjectDef(string sessionId, string objDefName);

Parameters
sessionId
objDefName
String containing the integration name for the object definition to delete
Output
Status text: Object ABC has been deleted
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 1180 for a description of the RelationshipDef XML node and an example
of its use.
Syntax
deleteObjectDef(string sessionId, string relName);
Parameters
sessionId
relName
String containing the integration name for the relationship definition to delete
Output
Status text: Field R123456 has been deleted

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
of its use.
Syntax
getApplicationDef(string sessionId, string appId);
Parameters
sessionId
appId
The original ID of the application to retrieve.
Output
XML document with the application definition in an Application node.
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.

its use.
Syntax
getFieldDef(string sessionId, string objDefName, string fieldDefName);
Parameters
sessionId
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.
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
of its use.
Syntax
getObjectDef(string sessionId, string objDefName);

Parameters
sessionId
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.
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);
Parameters
sessionId
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.

example of its use.
Syntax
getRelationshipDef(string sessionId, string relName);
Parameters
sessionId
relName
String containing the integration name of the relationship definition to retrieve
Output
An XML document with the relationship definition in a RelationshipDef node.
Example
The following example retrieves a relationship definition:
String xmlData = binding.getRelationshipDef(sessionId, "R123456");
metadataSearch()
Purpose
Searches for a string in metadata and returns results in XML format.
Syntax
metadataSearch(string sessionId, String query);
Parameters
sessionId
query
The string to search.

Output
An XML document with nodes for each metadata entity found for the search string.
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.
of its use.
Syntax
updateApplicationDef(string sessionId, string xmlString);
Parameters
sessionId
xmlString
XML description of the application in an Application node, including the objects to be updated
Output
Status text:
Application ABC has been updated
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.
its use.
Syntax
updateFieldDef(string sessionId, string xmlString);
Parameters
sessionId
xmlString
An XML string describing the field in an DataFieldDef node.
Output
Status text: Field ABC has been updated
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.
of its use.
Syntax
updateObjectDef(string sessionId, string xmlString);

Parameters
sessionId
xmlString
An XML string describing the object in an DataObjectDef node, along with fields and relationships.
Output
Status text: Object ABC has been updated
Example
The following example invokes updateObjectDef():
String infoMessage = binding.updateObjectDef(sessionId, xmlString);
updateRelationshipDef()
Purpose
Updates an existing relationship definition from an XML document.
example of its use.
Syntax
updateRelationshipDef(string sessionId, string xmlString);
Parameters
sessionId
xmlString
An XML string describing the field in an RelationshipDef node.
Output
Status text: Relationship R123456 has been updated

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
of its use.
HTTP Method
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 1259.
xmlString
An XML description of the application in an Application node, including the objects to be created.
Full administrative privileges
Response
Application ABC has been created

createFieldDef
Purpose
Creates a new field definition from an XML document.
its use.
HTTP Method
POST
URL
https://www.rollbase.com/rest/api/createFieldDef
URL Parameters
sessionId
xmlString
An XML description of the field in a DataFieldDef node.
Full administrative permissions
Response
Status text: Field ABC has been created
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
of its use.
HTTP Method
POST
URL
https://www.rollbase.com/rest/api/createObjectDef

URL Parameters
sessionId
xmlString
XML description of object in the DataObjectDef node, including the fields, and relationships to be
created.
Response
"test" object definition has been created. (ID=1953742)
createRelationshipDef
Purpose
Creates a new relationship definition from an XML document.
of its use.
HTTP Method
POST
URL
https://www.rollbase.com/rest/api/createRelationshipDef
URL Parameters
sessionId
xmlString
An XML description of the relationship in a RelationshipDef node.
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.
of its use.
HTTP Method
DELETE or GET
URL
https://www.rollbase.com/rest/api/deleteApplicationDef
URL Parameters
sessionId
appId
The original ID of the application.
Response
Application ABC has been deleted
deleteFieldDef
Purpose
Deletes a field definition from the specified object.
its use.
HTTP Method
DELETE or GET
URL
https://www.rollbase.com/rest/api/deleteFieldDef

URL Parameters
sessionId
objName
fieldName
Response
Status Text: Field ABC has been deleted
deleteObjectDef
Purpose
Permanently deletes an existing object definition, its components and its records.
of its use.
HTTP Method
DELETE or GET
URL
https://www.rollbase.com/rest/api/deleteObjectDef
URL Parameters
sessionId
objName
Response
Object ABC has been deleted

deleteRelationshipDef
Purpose
Deletes the relationship definition specified by the integration name.
of its use.
HTTP Method
DELETE or GET
URL
https://www.rollbase.com/rest/api/deleteRelationshipDef
URL Parameters
sessionId
relName
Response
Status text: Relatinship R123456 has been deleted
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
of its use.
HTTP Method
GET
URL
https://www.rollbase.com/rest/api/getApplicationDef

URL Parameters
sessionId
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>
• <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.
its use.
HTTP Method
GET
URL
https://www.rollbase.com/rest/api/getFieldDef
URL Parameters
sessionId
objName
fieldName
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

of its use.
HTTP Method
GET
URL
https://www.rollbase.com/rest/api/getObjectDef
URL Parameters
sessionId
objName
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
URL
https://www.rollbase.com/rest/api/getObjectDefNames
URL Parameters
sessionId
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.

Response
Names of object definitions in XML or JSON.
Example
Sample Response:
<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.
of its use.
HTTP Method
GET
URL
https://www.rollbase.com/rest/api/getRelationshipDef
URL Parameters
sessionId
relName
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
query
A text pattern to search.
Response
An XML document with nodes for each metadata entity found for the search string.
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" />
<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.

of its use.
HTTP Method
PUT or POST
URL
https://www.rollbase.com/rest/api/createApplicationDef
URL Parameters
sessionId
xmlString
Response
Application ABC has been updated
updateFieldDef
Purpose
Updates an existing field definition from an XML document.
its use.
HTTP Method
PUT or POST
URL
https://www.rollbase.com/rest/api/updateFieldDef
URL Parameters
sessionId
xmlString

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
of its use.
HTTP Method
PUT or POST
URL
https://www.rollbase.com/rest/api/updateObjectDef
URL Parameters
sessionId
xmlString
An XML description of the object in a DataObjectDef node, including fields and relationships.
Response
Object ABC has been updated
updateRelationshipDef
Purpose
Updates an existing Relationship definition from an XML document.
of its use.
HTTP Method
PUT or POST

URL
https://www.rollbase.com/rest/api/updateRelationshipDef
URL Parameters
sessionId
xmlString
An XML description of the relationship in a RelationshipDef node.
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}
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:
<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.
See REST Metadata Methods on page 1203 for information about REST metadata methods.
appXML
Purpose
Returns a Rollbase application as an XML document.
HTTP Method
GET
URL
https://www.rollbase.com/rest/api/appXML
URL Parameters
sessionId
appId
ID of application used to generate XML.
Response
Application XML
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
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
Create permission for the requested object type.
Response
Report on created record similar to report after CSV import
bulkCreateOrUpdate

Purpose
Updates existing records or creates new records from a bulk CSV upload. The output parameter is optional.
HTTP Method
POST
URL
https://www.rollbase.com/rest/api/bulkCreateOrUpdate
URL Parameters
sessionId
mapId
[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
import.
importMode

a full set of data.
createAction
output

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
ids
Comma-separated list of record IDs.
objName
output
Delete permission for the requested object type.
Response
Report on deleted record similar to report after CSVdelete.

bulkUpdate
Purpose
Updates records from a bulk CSV upload. The output parameter is optional.
HTTP Method
PUT or POST
URL
https://www.rollbase.com/rest/api/bulkUpdate
URL Parameters
sessionId
mapId
[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
import.
importMode

a full set of data.

createAction
output
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
output
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
objName
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
Response
The ID and integration name of the new record and a status of ok (see examples below).
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:
<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">
</data>
</composite>
</data>
This XML creates one "person" record and two related "payment" records in one call. Output example:
<resp status="ok">
<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
URL
https://www.rollbase.com/rest/api/createArr

URL Parameters
sessionId
output
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).
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:

<request>
</data>
<Field name="club_member">true</Field>
<Field name="lastName">Green</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"
}

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
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
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=myemail@mycompany.com&lastName=Admin
&loginName=myemail@mycompany.com&timeZone=PST
&mailSender=noreply@mycompany.com&password=my_password

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
1228, 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
objName
useIds
true or false.
output
The output format, one of: xml (default), json, or csv.
Parameter's name - integration name of field to set; parameter's value - value of field to set.

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">
<Msg>12 fields have been processed</Msg>
</resp>
createRecord
Purpose
Similar to create on page 1223, 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 699.
HTTP Method
POST
URL
https://www.rollbase.com/rest/api/createRecord
URL Parameters
sessionId
objName
useIds

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
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
&objName=USER&useIds=false&firstName=John&lastName=Smith&email=johns555@gmail.com&@p1=mypassword

<resp status="ok">
<data id=”314452” objName=”USER” />
</resp>

{
id: 314452
objName: "USER"
status: "ok"
}

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
id
Record's ID.
output
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.
connection), you must specify both the objName and id fields.

HTTP Method
DELETE or GET
URL
https://www.rollbase.com/rest/api/deleteArr
URL Parameters
sessionId
ids
Comma-separated list of record IDs.
output
Response
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

URL Parameters
sessionId
objName
id
The record ID.
output
Response
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
output

Response
Ids of all the applications available for the currently logged user.
Example
Sample Response:
<resp status="ok">
<ids>
<id>123456</id>
<id>123490</id>
</ids>
</resp>
getAuthentication
Purpose
Returns the authentication method 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
output
Response
The authentication for the tenant in XML or JSON format.
Examples
<resp status="ok">
<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>
<useKnowledgeFactorToken>true</useKnowledgeFactorToken>
<knowledgeFactorToken>email</knowledgeFactorToken>
</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>
</samlAttributeMap>
<samlAuthnContextComparison>minimum</samlAuthnContextComparison>
</resp>
getBinaryData
Purpose
Retrieves the file attachment associated with a particular file field from a specific record.
HTTP Method
GET method
URL
https://www.rollbase.com/rest/api/getBinaryData
URL Parameters
sessionId
objName
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.
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" } }
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

output
Response
Build and license information in XML format.
Example
Sample Response:
<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
URL
https://www.rollbase.com/rest/api/getCodeById
URL Parameters
sessionId
objName
field
id
Numeric ID of picklist item or status.

output
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 561 for more information about
views).
HTTP Method
GET
URL
https://www.rollbase.com/rest/api/getCount
URL Parameters
sessionId
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

Response
Total number of records in view
Example
Output example in XML:
<resp status="ok">
<count>100</count>
</resp>

{ "count": 100 }
getDataField
Purpose
Retrieves the value of a single field from a specific record.
HTTP Method
GET
URL
https://www.rollbase.com/rest/api/getDataField
URL Parameters
sessionId
objName
id
The record ID.
fieldName

useLegacyDateFormat
This optional URL parameter only applies to JSON output and, specifically, to DATE fields. If
useLegacyDateFormat=False, or is not specified, dates will be returned in the normal JSON
format, such as: "Wed Mar 05 17:52:38 IST 2014". If useLegacyDateFormat=True, dates
will be returned in a format similar to the following example: new Date("Wed Mar 05 2014
17:53:33 (IST)"). The following example shows results in normal and legacy formats:
• Normal:
{
"objName": "CUSTOMER",
"createdAt": "Wed Mar 05 17:52:38 IST 2014”
}
• Legacy:
{
"createdAt": new Date("Wed Mar 05 2014 17:53:33 (IST)")
}
output
Response
Field's value.
Example
<resp status="ok">
</resp>

{ "status": "Created" }
getDataObj
Purpose
Warning: This method is deprecated. Please change any existing code to use getRecord on page 1250,
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
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
Response
All of the field data for the specified object record.
Example
Output example for core record:

<resp status="ok">
<data id="131227" objName="person">

<Field name="id">131227</Field>
<Field name="updatedAt">20110111T143331Z</Field>
</data>
</resp>
Output example for core and related record (composite parameter set to 1):
<resp status="ok">
<Field name="R986">131228,131229</Field>
<composite>
<data id="131228" objName="payment">
<Field name="paym_date">20110115T143331Z</Field>
<Field name="R986">131227</Field>
</data>
</data>
</composite>
</data>
</resp>
getIdByCode
Purpose
Retrieves the ID of a picklist item or status by providing its integration code.
supported.
HTTP Method
GET
URL
https://www.rollbase.com/rest/api/getIdByCode
URL Parameters
sessionId
objName

field
code
Integration name of picklist item or status.
output
Response
ID of item with matching integration code or -1
Example
{ "id": 4567 }
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
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

output
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:

<resp status="ok">
<id>46219927</id>
</resp>
If the specified entity does not exist, returns an error message as shown below (in XML format):
<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
objName
The integration name of LDF dimension. It must be one of the following: $ORG_LOCN, $ORG_DEPT,
or $ORG_FUNC.
output
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" }
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
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
objNames
output.
fieldList
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.
onlyViewFields
output
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):
<resp status="ok">
<Field name="firstName">Bill</Field>
</data>
<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
• 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
roleId
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

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 1277 for the possible permissions
for each entity type.
Example
Output example in JSON format for entityType=application:
[
{
"name": "Progress Rollbase",
"id": "46219010",
"originalId": "836899",
"View": "true"
},
{
"name": "Organization Management",
"id": "46219031",
"View": "false"
},
{
"name": "Library",
"id": "46219857",
"View": "true"
},
{
"name": "Room Reservation",
"id": "46220403",
"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
userId
The ID of the user.
entityType
The type of entity for which permissions should be listed. Can be one of the following: object,
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
Response
The name, ID, original ID, and permissions granted for that user in XML or JSON format. See
setPermissionsByUser on page 1278 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",
"View": "true",
"Create": "false",
"Edit": "false",
"Delete": "false"
},
{
"name": "Room",
"id": "46219927",
"View": "true",
"Create": "true",
"Edit": "true",
"Delete": "true"
}
]
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
objName
fieldName
mainValueId
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.
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
sessionId
id
The record ID.
composite
objNames
output.
fieldList

output
Response
All of the field data for the specified object record and related records.
Example
Output example for core record:

<resp status="ok">
</data>
</resp>
Output example for core and related record (composite parameter set to 1):
<resp status="ok">
<Field name="R986">131228,131229</Field>
<composite>
</data>
</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
URL
https://www.rollbase.com/rest/api/getRelationships
URL Parameters
sessionId
objName
id
The record ID.
relName
fieldList
output
Response
IDs of related records
Example
<resp status="ok">
<ids>
<id>314452</id>
<id>128003</id>
</ids>
</resp>

[ 314452, 128003 ]

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
roleId
output
Response
The integration code, name, description, ID, and original ID of the role in XML or JSON format.
Example
<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",

"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
output
Response
A list of all roles in the tenant in XML or JSON format.
Example
[
{
"name": "Server API",
"code": null,
"description": "System role used to check permissions in Server-side API calls.",
"id": "98",
"originalId": "98"
},

{
"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"
}
]
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

objName
from
Beginning of date/time interval in ISO 8601 format.
till
End of date/time interval in ISO 8601 format.
output
Response
IDs of all records found in the search, returned as an array of longs
Example
<resp status="ok">
<ids>
<id>314452</id>
<id>128003</id>
</ids>
</resp>

[ 314452, 128003 ]
header
Purpose
Warning: This method is deprecated.
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
overrideChanges
A value of true or false. If true (default value), override changes made by administrative users.
output
Request Body
Application XML.
Response
Short report on application installation/update
Example
Output example:
<resp status="ok">
<Report>Application "Test" has been installed.</Report>
</resp>
installByAppId
Purpose
Installs or updates a Rollbase application published to the 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
id
ID of package record created for published application in Application Directory,
overrideChanges
A value of true or false. If true (default value), override changes made by administrative users.
output
Response
Short report on application installation/update
Example
Output example:
<resp status="ok">
<Report>Application "Test" has been installed.</Report>
</resp>
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

xmlString
A valid license XML string.
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.
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
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
Example
<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
output
Response
Example
<resp status="ok">
</resp>
resetPassword
Purpose
Resets the password of the specified user.
HTTP Method
POST
URL
https://www.rollbase.com/rest/api/resetPassword
URL Parameters
sessionId
loginName
Login name for an active Rollbase user account in the same tenant
output
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
objName
id
The record ID.
actionId
The original ID of the workflow action to run.
output
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 418 for details.
Response
The status in XML or JSON format. The following is an XML response upon success:
<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 419 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:

<resp status="ok">
<data id="366891304"></data>
</resp>
runTrigger
Purpose
Runs a trigger on an object.
HTTP Method
PUT or POST
URL
https://www.rollbase.com/rest/api/runTrigger
URL Parameters
sessionId
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
Response
Permissions
Example
&objName=person&id=314452&triggerId=TR1
Output example (in XML format):

<resp status="ok"> </resp>
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
output

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
<resp status="ok">
<ids>
<id>314452</id>
<id>128003</id>
</ids>
</resp>

[ 314452, 128003 ]
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
output
query

Response
Query result as decimal number
Example
Output: first element returned by query converted into number and wrapped in XML. Example:

<resp status="ok">
<value>53</value>
</resp>

{ "value": 53.0 }
selectQuery
Purpose
Runs an SQL SELECT query on the server and returns the results as a 2D-array.
all columns.

HTTP Method
GET
URL
https://www.rollbase.com/rest/api/selectQuery
URL Parameters
sessionId
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
output
The output format, one of: xml (default), json, or csv.
useLegacyDateFormat
• Normal:
{
}
• Legacy:
{
}
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

<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>

[
[ 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
URL Parameters
sessionId
output
query

useLegacyDateFormat
• Normal:
{
}
• Legacy:
{
}
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:

<resp status="ok">
<value>53</value>
</resp>

{ "value": 53.0 }
setAuthentication
Purpose
Sets the authentication method for the tenant and returns a success/failure response. Most URL parameters
are specific to a particular authentication type, which is indicated in each parameter description. This method
is only available for Rollbase Private Cloud.
HTTP Method
POST

URL
https://www.rollbase.com/rest/api/setAuthentication
URL Parameters
sessionId
output
authType
Specifies the authentication type. Valid values are:

• 0 — Password. See Password authentication on page 875 for more information.
• 1 — LDAP. See LDAP authentication details on page 883 for more information.
• 2 — HTTP POST. See HTTP POST authentication details on page 885 for more information.
• 3 — HTTP GET. See HTTP GET authentication details on page 886 for more information.
• 4 — Custom
• 6 — OpenEdge. See OpenEdge authentication details on page 886 for more information.
• 7 — LDAP Advanced. See LDAP advanced authentication details on page 883 for more information.
• 8 — Kerberos. See Kerberos authentication details on page 890 for more information.
• 9 — SAML/ADFS. See SAML/ADFS authentication details on page 891 for more information.
requestSignatureMethod
A signature method algorithm 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.
formula
For Password authentication, the custom validation formula.
useSecQuestions
For Password authentication, a true value specifies that users must create and answer security
questions.
mustAnswerQuestionsInProfile
For Password authentication, the number of security questions a user must answer. Valid values
are 2, 3, and 4.
mustAnswerPreviouslyAnswered
For Password authentication, the number of previously answered security questions a user must
answer to be authenticated. Valid values are 1 and 2.

securityLevel
For Password authentication, the security level as a number, where 1=low, 2=medium, and 3=high.
expirPolicy
For Password authentication, 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
For Password authentication, security questions, where X is a number between 0 and 11. A maximum
of 12 security questions is allowed.
useKnowledgeFactorToken
For passowrd authentication, this must be set to true to use a knowledge factor token. See User
authentication and password management on page 759 for more information.
knowledgeFactorToken
For passowrd authentication, 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 759 for more
information.
targetURL
For LDAP, LDAP Advanced, HTTP POST, and HTTP GET authentication, the target URL.
securityAuthentication
For LDAP authentication, the authentication mechanism to implement. See LDAP authentication
details on page 883 for details.
securityPrincipal
For LDAP authentication, the name of the user or program doing the authentication. Typically, this
is a query string to search the LDAP database.
securityCredential
For LDAP authentication, the credentials of the user or program doing the authentication.
additionalParamKeys
For LDAP authentication, a JSON array of keys for additional parameters. Only one additional
parameter is currently allowed.
additionalParamValues
For LDAP authentication, a JSON array of values for additional parameters. Only one additional
parameter is currently allowed.
idpCertificateFileContent
Content of the IDP metadata file.

idpFileContentType
Type of the IDP metadata file.
idpCertificateFileName
This is an optional parameter.
responseText
For HTTP POST and HTTP GET authentication, text that must be present in HTTP response to
indicate whether the authentication was successful.
httpBody
For HTTP POST and HTTP GET authentication, the template for the body of the HTTP POST request
(typically a SOAP call). This must include tokens for user input.
headerKeys
For HTTP POST and HTTP GET authentication, 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
For HTTP POST and HTTP GET authentication, a JSON array of header values. The first header
value for HTTP POST must be the content type. Only five headers are currently allowed.
realmURL
For OpenEdge authentication, the realm URL. See OpenEdge authentication details on page 886 for
details.
realmClass
For OpenEdge authentication, the realm class. See OpenEdge authentication details on page 886
for details.
openEdgeDomain
For OpenEdge authentication, the name of the domain to which the OpenEdge user must belong.
See OpenEdge authentication details on page 886 for details.
openEdgeAccessCode
For OpenEdge authentication, the code or key required for an OpenEdge user to access the
OpenEdge domain. See OpenEdge authentication details on page 886 for details.
noHostVerify
For OpenEdge authentication. If true, OpenEdge authentication will not validate the hostname of
the OpenEdge realm URL. See OpenEdge authentication details on page 886 for details.
managePassword
For OpenEdge authentication, enables password management options. See OpenEdge authentication
details on page 886 for details.

passwordGuidelines
For OpenEdge authentication, the text on the Change Password page that describes password
guidelines. The managePassword parameter must be true in order to set this parameter.
suLoginname
For OpenEdge authentication, the Super Admin login name.
suPassword
For OpenEdge authentication, the Super Admin password.
guestLoginname
For OpenEdge authentication, the guest login name.
guestPassword
For OpenEdge authentication, the guest password.
certJarFileContent
For OpenEdge authentication, the certificate JAR file content. It should be a Base64 encoded string.
certJarFileName
For OpenEdge authentication, the certificate JAR file name.
certJarFileContentType
For OpenEdge authentication, the certificate JAR file content type.
tokenFileContent
For OpenEdge authentication, the token file content. It should be a Base64 encoded string.
tokenFileName
For OpenEdge authentication, the token file name.
tokenFileContentType
For OpenEdge authentication, the token file content type.
baseDistinguishedName
For LDAP Advanced authentication, the root distinguished name (DN) to use while running queries
against your directory server. See LDAP advanced authentication details on page 883 for more
information.
additionalUserDN
For LDAP Advanced authentication, the value to be used in addition to the base DN when searching
for and loading users. See LDAP advanced authentication details on page 883 for more information.

authenticationType
For LDAP Advanced authentication, the authentication mechanism to implement. See LDAP advanced
searchCapabilities
For LDAP Advanced authentication, the LDAP authentication requirements to search for and get
results from a search query. Valid values are Anonymous and Authenticated. See LDAP advanced
adminSecurityPrincipal
For LDAP Advanced authentication, the admin security principal. This parameter is only applicable
if searchCapabilities is Authenticated. See LDAP advanced authentication details on page
adminSecurityCredential
For LDAP Advanced authentication, the admin security credential. This parameter is only applicable
if searchCapabilities is Authenticated. See LDAP advanced authentication details on page
userNameAttribute
For LDAP Advanced authentication, the attribute field to use when loading the user name. See LDAP
advanced authentication details on page 883 for more information.
additionalParamKeys
For LDAP Advanced authentication, a JSON array of keys for additional parameters. Only one
additional parameter is currently allowed.
additionalParamValues
For LDAP Advanced authentication, a JSON array of values for additional parameters. Only one
additional parameter is currently allowed.
passwordActivationContextExpiry
For passowrd authentication, the password activation link expiry time. See User authentication and
password management on page 759 for more information.
samlAuthnContextComparison
For SAML/ADFS authentication, 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 details for a tenant on
Response
The authentication for the tenant in XML or JSON format.

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
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
sessionId
Response
Status message wrapped in XML

setDataField
Purpose
Sets the value of a single field for a specific record.
HTTP Method
GET or POST
URL
https://www.rollbase.com/rest/api/setDataField
URL Parameters
sessionId
objName
id
The record ID.
fieldName
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

Response
Status message wrapped in XML
Example
Output example:
<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
roleId
entityType
The type of entity for which permissions should be set. Can be one of the following: field, object,
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
Response
The status in XML or JSON format.
Example
<resp status="ok">
</resp>
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
userId
The ID of the user.

entityType
The type of entity for which permissions should be set. Can be one of the following: object,
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
Response
The status in XML or JSON format.
Example
<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
objName
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.
Response
Example
Input example:
<data objName="person" id="314452" useIds="false">
</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:
<data objName="person" id="314452" useIds="false">
<composite>
<data objName="payment" id="314453" useIds="false">
</data>
<data objName="payment" id="314454" useIds="false">
</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
objName
output
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.
Edit permission for the requested object types.
Response

Example
Input example:
<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
URL Parameters
sessionId
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.
Parameter's name - integration name of field to set; parameter's value - value of field to set. Same
for other fields.
output

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 699.
HTTP Method
PUT or POST
URL
https://www.rollbase.com/rest/api/updateRecord
URL Parameters
sessionId
objName
useIds
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

Response
Example
&objName=person&id=314452&useIds=false&club_member=false&lastName=Smith&status=Created

{"status":"ok"}
update2
Warning: This method is deprecated. Please change any existing code to use updateRecord on page
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
id
The record ID.
useIds

Rollbase SOAP Methods
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.
Response
Example
&id=314452&useIds=false&club_member=false&lastName=Smith&status=Created
Output example:
<resp status="ok">
</resp>
view
Purpose
Warning: This method is deprecated.

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.
• 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.
See SOAP Metadata Methods on page 1190 for information about SOAP metadata methods.
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.
DataFieldArr
An array of DataField instances containing the values for the record's fields.
Example
See getRecord() on page 1313 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 1292, getDataField() on page 1305, and setDataField() on page 1321 for examples.
SearchFilter Class
Purpose
Defines a single search filter for the detailedSearch() on page 1301 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 502 component.

• EQ equals
• NEQ not equal
• ST starts with
• CT contains
• 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.
Syntax
bulkCreate(string sessionId, string mapId, boolean sync, string csvString);
Parameters
sessionId
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
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

mapId
uniqueFieldId
ID of a unique field used to identify the records to be updated
uniqueCombinationId
ID of a Unique Fields Combination trigger
sync
csvString
Output
Comma-separated IDs of updated records for synchronous update
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
mapId
uniqueFieldId
ID of unique field used to identify records to be updated

uniqueCombinationId
ID of the Unique Fields Combination trigger
sync
csvString
Output
Comma-separated IDs of updated records for synchronous update
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
Output
None
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 1297
Syntax
create(string sessionId, string objDefName, DataFieldArr arr, boolean useIds);
Parameters
sessionId
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
Output
ID of newly created record as a long
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)
• 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.
a D2C connection), you can use the method, createArr2() on page 1294.
Syntax
createArr(string sessionId, DataObjArr arr, boolean useIds);
Parameters
sessionId
arr
A DataObjArr array of DataObjs with data for new records. Record IDs and auto-numbers are
assigned automatically.
useIds
Output
Ids of newly created records as a LongArr
Example
// Array of transport objects to be sent to createArr
DataObj[] arr = new DataObj[10];
// Populate data Fields to be set for record 0

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);
createArr2()
Purpose
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 1293.
Syntax
createArr2(string sessionId, DataObjArr arr, boolean useIds);
Parameters
sessionId
arr
useIds
Output
Ids of newly created records as a StringArr

Example
// Array of transport objects to be sent to createArr
// Populate data Fields to be set for record 0

Field.setValue("1000");
Fields[0]=Field;
// Create record 0
arr[0] = obj;
// 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
arr
useIds
Output
Ids of newly created records as a LongArr

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
arr
useIds
Output
ID of newly created Customer
Create permission for the Customer object type
Example
DataField[] arr = new DataField[7];
arr[0] = getField("companyName", "API Test");
arr[1] = getField("email", "myemail@mycompany.com");
arr[2] = getField("lastName", "Admin");
arr[3] = getField("loginName", "myemail@mycompany.com");
arr[4] = getField("timeZone", "Pacific/Guam");
arr[5] = getField("mailSender", "noreply@mycompany.com");
arr[6] = getField("password", "my_password");
binding.createCustomer(sessionId, new DataFieldArr(arr), true);

createRecord()
Purpose
Similar to create() on page 1292, creates a new record. Returns the ID of the newly created record.
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
objDefName
arr
useIds
Output
The ID of the newly created record as a string.
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 1299.
Syntax
delete(string sessionId, long id);

Parameters
sessionId
id
Output
None
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.
a D2C connection), you can use the method, deleteRecords() on page 1300.
Syntax
deleteArr(string sessionId, LongArr ids);
Parameters
sessionId
ids
LongArr array of record ids to be deleted.
Output
None

Example
long[] ids = new long[] { 123456, 123457 };
binding.deleteArr(sessionId, new LongArr(ids));
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.
a D2C connection), you can use the method, deleteRecords() on page 1300.
Syntax
deleteArrNoAudit(string sessionId, LongArr ids);
Parameters
sessionId
ids
LongArr array of record ids to be deleted.
Output
None
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
objDefName
uid
Output
None.
deleteRecords()
Purpose
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 1298 and deleteArrNoAudit()
on page 1299.
Syntax
deleteRecords(string sessionId, String objDefName, StringArr ids, Boolean
blockAudit);
Parameters
sessionId
objDefName
ids
StringArr array of record ids to be deleted.
blockAudit
If set to true, no audit records are created.

Output
None
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 502 component.
Syntax
detailedSearch(string sessionId, string query, string objDefName, SearchFilterArr
filterArr, string joinType, string expression)
Parameters
sessionId
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
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
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);

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
id
fieldName
A string containing the field integration name.
Output
Binary data (file attachment) from specified file Field wrapped in a ByteArr
Example
long id = 123456;
ByteArr arr = binding.getBinaryData(sessionId, id, "picture");
if (arr != null {
byte[] data = arr.getArr();
}

getCodebyId()
Purpose
Retrieves the integration code of a picklist item or status by ID.
supported.
Syntax
getCodeById(string sessionId, string objDefName, string fieldName, long id);
Parameters
sessionId
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 561 for more information about
views).
Syntax
getCount(string sessionId, string viewId, string filterName, string filterValue);

Parameters
sessionId
viewId
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
Example
int count = binding.getCount("7ae747a0e36648ef8bd016eec1502779@46216462", "123",
"lastName", "Grey");
getIdByCode()
Purpose
Retrieves the ID of the pick item or status by integration code.
supported.
Syntax
getIdByCode(string sessionId, string objDefName, string fieldName, string code);
Parameters
sessionId
objDefName
String containing integration name of object definition

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.
a D2C connection), you can use the method, getDataField2() on page 1306.
Syntax
getDataField(string sessionId, long id, string fieldName, boolean useIds);
Parameters
sessionId
id
fieldName
useIds
Output
Field's value wrapped in a DataField container.

Example
long id = 123456;
DataField field = binding.getDataField(sessionId, id, "lastName", false);
if (field != null) {
String lastName = field.getValue();
}
getDataField2()
Purpose
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 1305.
Syntax
getDataField2(string sessionId, String objDefName, String uid, String fieldName,
Boolean useIds);
Parameters
sessionId
objDefName
uid
fieldName
useIds
Output
Field's value wrapped in a DataField container.

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
Retrieves all field data, including formulas, for a given record.
Syntax
getDataObj(string sessionId, long id, boolean useIds);
Parameters
sessionId
id
useIds
Output
All of the field data for the specified object record. Each field value is wrapped in a DataField container.
VIEW permission for requested record
Example
long id = 123456;
DataObj obj = binding.getDataObj(sessionId, id, true);
if (obj != null) {
DataField[] fields = obj.getFields();
}

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
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);

Parameters
sessionId
viewId
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
Output
Selected records as DataObjArr
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());
for (DataField field: fields) {
System.out.println("Name="+field.getName()+
" Value="+field.getValue());
}
}

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
objDefName
id
relName
A string containing the relationship integration name.
Output
A stringArr containing a list of related record IDs.
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.

Note: This method does not work for external objects. Use getRelatedIDs() on page 1310 for external objects,
including those mapped to OpenEdge services.
Syntax
getRelationships(string sessionId, long id, string relName);
Parameters
sessionId
id
relName
Relationship's integration name
Output
IDs of related records wrapped in a LongArr
View permission for the requested object types.
Example
long id = 123456;
LongArr arr = binding.getRelationships(sessionId, id, "R76543");
if (arr != null {
}
getRuntimeStatus()
Purpose
Retrieves the runtime status of the Customer on the Web API server.
Syntax
getRuntimeStatus(string sessionId, long id);
Parameters
sessionId

id
Output
Runtime status:
• RUNTIME_ERROR = -1;
• RUNTIME_UNLOADED = 1;
• RUNTIME_LOADED = 2;
• RUNTIME_LOADING = 3;
• RUNTIME_CREATING = 4;
• RUNTIME_BUSY = 5;
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
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

Output
Example
Calendar from = Calendar.getInstance();
from.setTime(...);
Calendar till = null;
LongArr arr = binding.getUpdated(sessionId, from, till, "lead");

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
objDefName
uid
A string containing the object ID.
useIds
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 1287 for more information.
Example
DataObj obj = binding.getRecord(sessionId, "client", "123456", true);

if (obj != null) {
}
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
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);

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
logout()
Purpose
Terminates the specified API session. This method should be called to explicitly end each SOAP session.
Syntax
logout(string sessionID);
Parameters
sessionId
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);

resetPassword()
Purpose
Resets the password of the specified user.
Syntax
resetPassword(string sessionId, string loginName);
Parameters
sessionId
loginName
Login name for an active Rollbase user account in the same tenant
Output
None
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.
all columns.


Syntax
selectNumber(string sessionId, string query);
Parameters
sessionId
query
An SQL SELECT query. See the examples described for selectQuery().
Output
Single result of the SELECT query as a decimal number
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 Adding Logic to an Application 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

all columns.
Syntax
selectQuery(string sessionId, string query, int maxRows);
Parameters
sessionId
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
Example
StringArr2D values = binding.selectQuery(sessionId, "SELECT loginName, firstName, lastName
FROM USER ORDER BY lastLogin DESC", 10);

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.
all columns.
Syntax
selectValue(string sessionId, string query);
Parameters
sessionId
query
An SQL SELECT query. See the examples described for selectQuery().

Output
Single result of SELECT query as string
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
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

suggestedFileName
Suggested file name (with valid file extension)
binData
File's binary data wrapped in a ByteArr
Output
None
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.
a D2C connection), you can use the method, setDataField2() on page 1322.
Syntax
setDataField(string sessionId, string id, DataField df, boolean useIds);
Parameters
sessionId
id
df
A new value for the field wrapped in a DataField container.

useIds
Output
None
Example
// Populate data Field to be set for existing record
Field.setName("R34567");
Field.setValue("100088,100089");
// Call setDataField API

long id = 123456; // Record id - required
binding.setDataField(sessionId, id, Field, true);
setDataField2()
Purpose
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 1321.
Syntax
setDataField2(string sessionId, String objDefName, String uid, DataField df,
Boolean useIds);
Parameters
sessionId
objDefName
uid

df
A new value for the field wrapped in a DataField container.
useIds
Output
None
Example
// Populate data Field to be set for existing record
// 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
srcCode
The currency code to convert from.
destCode
The currency code to convert to.
date
The Calandar object containing the date.

rate
Double containing rate to be set
Output
None
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.
a D2C connection), you can use the method, setRelatedIDs() on page 1325.
Syntax
setRelationship(string sessionId, long id, string relName, LongArr arr);
Parameters
sessionId
id
relName
arr
Output
None

Example
long id = 123456;
long[] arr = new long[] { 100890, 100891 };
binding.setRelationships(sessionId, id, "R1223456", new LongArr(arr));
setRelatedIDs()
Purpose
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 1324.
Syntax
setRelatedIDs(string sessionId, String objDefName, String uid, String relName,
StringArr arr);
Parameters
sessionId
objDefName
uid
relName
arr
Output
None

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
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
Example
LongArr arr = binding.textSearch(sessionId, "John Smith", "lead");
update()
Purpose
Updates an existing record.
This method only works with native Rollbase objects. To update an external object record, see updateRecord
on page 1330.

Syntax
update(string sessionId, long id, DataFieldArr arr, boolean useIds);
Parameters
sessionId
id
arr
useIds
Output
None
Example
// Populate data Fields to be updated for existing record
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);

Parameters
sessionId
arr
An Array of DataObj instances with data for existing records. DataObj instances must include
valid record IDs.
useIds
Output
None
Example
// Array of transport objects to be sent to updateArr
// Populate data Fields to be updated for record 0

Field.setValue(1000);
Fields[0]=Field;
// Update record 0
obj.setId(123456); // Required for update
arr[0] = obj;
// 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.

Syntax
updateArrNoAudit(string sessionId, DataObj arr);
Parameters
sessionId
arr
An Array of DataObj instances with data for existing records. DataObj instances must include
valid record IDs.
useIds
Output
None
updateCustomer()
Purpose
Updates a Customer record with the supplied values.
Syntax
updateCustomer(string sessionId, long id, arr, useIds);
Parameters
sessionId
id
The customer ID.
arr
Values for fields to be updated.

useIds
Output
None
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
objDefName
uid
arr

Rollbase CSS Styles for the Classic UI
useIds
Output
None.

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.
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

CSS Class Name Description
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
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
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.

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.
td.rbs_errorLabelRight Renders error column in a 2 column layout pages that

has the field labels that are not required. This style is
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
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
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
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
td.rbs_rightWideLabelRequired Renders column in a single column layout pages that

has the field labels that are required. This style is more
record pages.
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.
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.

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.
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,
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,
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,
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,

Text Styles
the following CSS classes define Rollbase text styles.
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

info in that is gray and bold.
rbs_infoMessage Renders the messages in #FFF1A8 color
rbs_InfoSmallWide Renders detailed information that describes various

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

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
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.
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.

Field types
Sidebar Styles
The following CSS classes define Rollbase sidebar styles.
rbs_sidebarContent Renders the column that has the entire sidebar content
rbs_sidebarLink Render links in side bar
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 815)
• 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 1352 for information about enabling and disabling inline editing. See Inline editing on page 572 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 692 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.
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 306 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 807 for
supported currency formats.
• Default value for new records.
• Minimum allowed value for this field.
• Maximum allowed value for this field.

Field types
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
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 477 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 306 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 306 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 page on page 793.
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
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 725 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.

Field types
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 306 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.
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.

Field types
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 309.
• 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.
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. This number is incremented for each new record created. An Auto-number format may also
include year, month and day. When you create an auto-number Field you can 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.
Note: Every time you request for a new record creation through UI, the auto-number is incremented.
However, if you remove the auto-number field from the Create page, it will be incremented only when a new
record is saved.
Tip: It is common to use Auto-Number Fields in Object definition name templates.

Important: Auto-Number fields are read-only when new record is created. However you can edit value of field
on Edit record page.
Important: New number for Auto-Number field is assigned when user saves new record.
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.
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.

Field types
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 555 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.
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 555 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 555 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 312, 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 373.
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 362. 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 990.
• 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
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}";

Field types
return "{!star3}";
return "{!star4}";
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:
• The JavaScript code for expression fields cannot include loops and references to related records. However,
you can use the server-side API to query an expression field.
• The expression field value will not be updated when related records are updated.
• 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.
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.
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 381.
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 381.
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.
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.

Field types
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.
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 44 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 338. 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.
System Field Types

The following field types are Rollbase system fields.

Field types
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.
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 748.
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 724 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.
Portal Field Types

The following Field types are typically only used in external-facing Portals. See Rollbase portals on page 594.
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 594 for more information.

Field types
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 594. 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.


15
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.

Chapter 15: Getting help

16
Third-party acknowledgements
The following notices apply to Rollbase hosted and private cloud.
• Rollbase Public Cloud Third-party acknowledgements
• Rollbase Private Cloud Third-party acknowledgements
Rollbase Public Cloud Third-party acknowledgements

One or more products in the Progress Rollbase Public Cloud v4.5 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.
In compliance with the following PREAMBLE section of the SIL OPEN FONT LICENSE Version 1.1 – 26
February 2007, Dancing Script Font, Font Awesome Fonts v4.7.0, Noto Sans Ethiopic Bold font v1.08, and
Noto Sans Ethiopic font v1.0.8 are released only under the SIL OPEN FONT LICENSE Version 1.1 – 26
February 2007 (see full license text below):
PREAMBLE
The goals of the Open Font License (OFL) are to stimulate worldwide development of collaborative font projects,
to support the font creation efforts of academic and linguistic communities, and to provide a free and open
framework in which fonts may be shared and improved in partnership with others.

Chapter 16: Third-party acknowledgements
The OFL allows the licensed fonts to be used, studied, modified and redistributed freely as long as they are
not sold by themselves. The fonts, including any derivative works, can be bundled, embedded, redistributed
and/or sold with any software provided that any reserved names are not used by derivative works. The fonts
and derivatives, however, cannot be released under any other type of license. The requirement for fonts to
remain under this license does not apply to any document created using the fonts or their derivatives.
Progress Rollbase Public Cloud v4.5 incorporates Exchange Integration v2.0. Such technology is subject to
the following terms and conditions:
The MIT License
Copyright (c) 2012 Microsoft Corporation
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, sublicense, and/or sell copies of the Software, and to permit
persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of
the Software.
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. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF
CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE
OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
Progress Rollbase Public Cloud v4.5 incorporates jquery.min.js v1.7.1. Such technology is subject to the
following terms and conditions:
Copyright (c) 2011 John Resig, http://jquery.com/
rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to
permit persons to whom the Software is furnished to do so, subject to the following conditions:
the Software.
CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
Progress Rollbase Public Cloud v4.5 incorporates icu4j v54.1.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.
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.

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.
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.

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
---------COPYING.libtabe ---- BEGIN--------------------/*
Copyright (c) 1999 TaBE Project. Copyright (c) 1999 Pai-Hsiang Hsiao. All rights reserved.
. 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
. 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.
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
Copyright (c) 1999 Computer Systems and Communication Lab,
Institute of Information Science, Academia Sinica.


disclaimer.
. 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.
Copyright 1996 Chih-Hao Tsai @ Beckman Institute, University of Illinois c-tsai4@uiuc.edu
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.
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.
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.
SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
---------------------------------------------------------------------
4. Burmese Word Break Dictionary Data (burmesedict.txt)
This list is part of a project hosted at:
github.com/kanyawtech/myanmar-karen-word-lists
--------------------------------------------------------------------- Copyright (c) 2013, LeRoy Benjamin Sharon

disclaimer.
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.
---------------------------------------------------------------------
5. Time Zone Database
ICU uses the public domain data and code derived from Time Zone Database for its Time Zone Database
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 Public Cloud v4.5 incorporates Java Cryptography APIs v1.54. Such technology is subject
to the following terms and conditions: Copyright (c) 2000 - 2015 The Legion of the Bouncy Castle Inc.
(http://www.bouncycastle.org)
the Software.
Progress Rollbase Public Cloud v4.5 incorporates JQuery Mobile Framework v1.0.1 (including i.JQuery
hashchange event v1.3). Such technology is subject to the following terms and conditions:

Copyright 2010, 2013 jQuery Foundation, Inc. and other contributors,

http://jquery.com/
the Software.
Progress Rollbase Public Cloud v4.5 incorporates JQuery UI v1.8.18. Such technology is subject to the following
terms and conditions:
Copyright (c) 2010 Paul Bakaus, http://jqueryui.com/
This software consists of voluntary contributions made by many individuals (AUTHORS.txt,
http://jqueryui.com/about) For exact contribution history, see the revision history and logs, available at
http://jquery-ui.googlecode.com/svn/
the Software.
Progress Rollbase Public Cloud v4.5 incorporates SLF4J Log4j v1.75 and SLF4J API v1.7.5. Such technology
is subject to the following terms and conditions:
Copyright (c) 2004-2013 QOS.ch 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,
sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do
so, subject to the following conditions: The above copyright notice and this permission notice shall be included
in all copies or substantial portions of the Software. 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. IN NO
EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR
OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

Progress Rollbase Public Cloud v4.5 incorporates qTip v2.2. Such technology is subject to the following terms
and conditions: Copyright (c) 2012 Craig Michael Thompson - 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, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
the Software.
Progress Rollbase Public Cloud v4.5 incorporates CodeMirror v5.16. Such technology is subject to the following
Copyright (C) 2016 by Marijn Haverbeke <marijnh@gmail.com> and others
rights
the Software.
Progress Rollbase Public Cloud v4.5 incorporates Bootstrap Responsive v3.3.6. Such technology is subject
to the following terms and conditions: The MIT License (MIT)
Copyright (c) 2011-2016 Twitter, Inc.
rights
the Software.
Progress Rollbase Public Cloud v4.5 incorporates Font-Awesome Code v4.6.3. Such technology is subject to
the following terms and conditions: Font-Awesome Fonts v4.5. Such technology is subject to the following
terms and conditions Font Awesome 4.6.3 by @davegandy - http://fontawesome.io - @fontawesome

License - http://fontawesome.io/license (Font: SIL OFL 1.1, CSS: MIT License)

The MIT License (MIT)
Copyright (c) <year> <copyright holders>
the Software.
Progress Rollbase Public Cloud v4.5 incorporates Font-Awesome Fonts v4.6.3, Noto Sans Ethiopic Bold font
v1.08, and Noto Sans Ethiopic font v1.0.8. These technologies are subject to the following terms and conditions:
Font Awesome 4.5.0 by @davegandy - http://fontawesome.io - @fontawesome
License - http://fontawesome.io/license (Font: SIL OFL 1.1, CSS: MIT License)
Copyright (c) 2010, Pablo Impallari (www.impallari.com|impallari@gmail.com),
Copyright (c) 2010, Igino Marini. (www.ikern.com|mail@iginomarini.com),
with Reserved Font Name Dancing Script.
This Font Software is licensed under the SIL Open Font License, Version 1.1.
This license is copied below, and is also available with a FAQ at:
http://scripts.sil.org/OFL
-----------------------------------------------------------
SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
-----------------------------------------------------------
PREAMBLE
The goals of the Open Font License (OFL) are to stimulate worldwide development of collaborative font projects,
to support the font creation efforts of academic and linguistic communities, and to provide a free and open
framework in which fonts may be shared and improved in partnership with others.
The OFL allows the licensed fonts to be used, studied, modified and redistributed freely as long as they are
not sold by themselves. The fonts, including any derivative works, can be bundled, embedded, redistributed
and/or sold with any software provided that any reserved names are not used by derivative works. The fonts
and derivatives, however, cannot be released under any other type of license. The requirement for fonts to
remain under this license does not apply to any document created using the fonts or their derivatives.
DEFINITIONS
"Font Software" refers to the set of files released by the Copyright Holder(s) under this license and clearly
marked as such. This may include source files, build scripts and documentation.
"Reserved Font Name" refers to any names specified as such after the copyright statement(s).
"Original Version" refers to the collection of Font Software components as distributed by the Copyright Holder(s).

"Modified Version" refers to any derivative made by adding to, deleting, or substituting -- in part or in whole --
any of the components of the Original Version, by changing formats or by porting the Font Software to a new
environment.
"Author" refers to any designer, engineer, programmer, technical writer or other person who contributed to the
Font Software.
PERMISSION & CONDITIONS
Permission is hereby granted, free of charge, to any person obtaining a copy of the Font Software, to use,
study, copy, merge, embed, modify, redistribute, and sell modified and unmodified copies of the Font Software,
subject to the following conditions:
1) Neither the Font Software nor any of its individual components, in Original or Modified Versions, may be
sold by itself.
2) Original or Modified Versions of the Font Software may be bundled, redistributed and/or sold with any
software, provided that each copy contains the above copyright notice and this license. These can be included
either as stand-alone text files, human-readable headers or in the appropriate machine-readable metadata
fields within text or binary files as long as those fields can be easily viewed by the user.
3) No Modified Version of the Font Software may use the Reserved Font
Name(s) unless explicit written permission is granted by the corresponding Copyright Holder. This restriction
only applies to the primary font name as presented to the users.
4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
Software shall not be used to promote, endorse or advertise any Modified Version, except to acknowledge the
contribution(s) of the Copyright Holder(s) and the Author(s) or with their explicit written permission.
5) The Font Software, modified or unmodified, in part or in whole, must be distributed entirely under this license,
and must not be distributed under any other license. The requirement for fonts to remain under this license
does not apply to any document created using the Font Software.
TERMINATION
This license becomes null and void if any of the above conditions are not met.
DISCLAIMER
THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF MERCHANTABILITY, FITNESS FOR
A PARTICULAR PURPOSE AND NONINFRINGEMENT OF COPYRIGHT, PATENT, TRADEMARK, OR
OTHER RIGHT. IN NO EVENT SHALL THE COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES
OR OTHER LIABILITY, INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR
CONSEQUENTIAL DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM OTHER DEALINGS
IN THE FONT SOFTWARE.
Progress Rollbase Public Cloud v4.5 incorporates Bootstrap-rtl v3.3.6. Such technology is subject to the
following terms and conditions:
The MIT License (MIT)
Copyright (c) 2011-2016 Twitter, Inc.
the Software.

Progress Rollbase Public Cloud v4.5 incorporates Mockito Mock Library for Java v1.10.9. This technology is
subject to the following terms and conditions:
The MIT License
Copyright (c) 2007 Mockito contributors
the Software.
PSC will, at Licensee’s request, provide a copy of the source code for the following third-party technologies,
including modifications, if any, made by PSC. PSC may charge reasonable shipping and handling charges for
such distribution. Licensee may also obtain the source code/license for this third-party technology through
http://iue.progress.com/3dpartysoftwares/Pages/default.aspx by following the instructions set forth therein.
- Progress Rollbase Public Cloud v4.5 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.
Such technology is subject to the terms and conditions of the Mozilla Public License, Version 2.0.
- Progress Rollbase Public Cloud v4.5 incorporates JavaMail v1.5.2, jax-rpc v1.1, and JavaBeans Activation
Framework (JAF) v1.0.2. Such technologies are subject to the terms and conditions of the Common Development
and Distribution License, Version 1.0.
- Progress Rollbase Public Cloud v4.5 incorporates servlet-api.jar v3.0, Java API for Processing JSON (Default
provider) v1.0.4, and Java API for Processing JSON (API module) v1.0. Such technology is subject to the terms
and conditions of the Common Development and Distribution License, Version 1.1.
Updated 2/1//2018
Rollbase Private Cloud Third-party acknowledgements

One or more products in the Progress Rollbase Private Cloud v4.5 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 v4.5 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.

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 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 apache@apache.org.
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 `ÀS 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 v4.5 incorporates ESAPI v2.1.0. Such technology is subject to the following
terms and conditions: The BSD License
Copyright (c) 2007, The OWASP Foundation All rights reserved.
disclaimer.
Neither the name of the OWASP Foundation nor the names of its contributors may be used to endorse or

Progress Rollbase Private Cloud v4.5 incorporates Jaxen-1.1.jar v1.1. Such technology is subject to the following
Copyright 2003-2006 The Werken Company. All Rights Reserved.
disclaimer.
Neither the name of the Jaxen Project nor the names of its contributors may be used to endorse or promote
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
Progress Rollbase Private Cloud v4.5 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.
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 `ÀS 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
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 v4.5 incorporates lsimplecaptcha.jar v1.2.1. Such technology is subject to
the following terms and conditions: Copyright (c) 2008, James Childers All rights reserved.
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
o Neither the name of SimpleCaptcha nor the names of its contributors may be used to endorse or promote
Progress Rollbase Private Cloud v4.5 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
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 dom4j-info@metastuff.com.
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 `ÀS IS'' AND ANY
EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
SHALL METASTUFF, LTD. OR ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
Progress Rollbase Private Cloud v4.5 incorporates icu4j v54.1.1. Such technology is subject to the following
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.
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.
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.
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.
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.
disclaimer.
Neither the name of Google Inc. nor the names of its contributors may be used to endorse or promote products
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
IPADIC (Japanese)
- http://chasen.aist-nara.ac.jp/chasen/distribution.html
---------COPYING.libtabe ---- BEGIN--------------------/*
Copyrighy (c) 1999 TaBE Project.

Copyright (c) 1999 Pai-Hsiang Hsiao.

disclaimer.
. Neither the name of the TaBE Project nor the names of its contributors may be used to endorse or promote
Copyright (c) 1999 Computer Systems and Communication Lab,
Institute of Information Science, Academia Sinica.
disclaimer.
. 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.
Copyright 1996 Chih-Hao Tsai @ Beckman Institute, University of Illinois c-tsai4@uiuc.edu
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.
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)
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.

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.
---------------------------------------------------------------------
4. Burmese Word Break Dictionary Data (burmesedict.txt)
This list is part of a project hosted at:
github.com/kanyawtech/myanmar-karen-word-lists
--------------------------------------------------------------------- Copyright (c) 2013, LeRoy Benjamin Sharon
disclaimer.
Neither the name Myanmar Karen Word Lists, nor the names of its contributors may be used to endorse or
---------------------------------------------------------------------
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 v4.5 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:
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.
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.
disclaimer.
Neither the name of the Hypersonic SQL Group nor the names of its contributors may be used to endorse or

SHALL THE HYPERSONIC SQL GROUP, OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
This software consists of voluntary contributions made by many individuals on behalf of the Hypersonic SQL
Group.
Progress Rollbase Private Cloud v4.5 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.
disclaimer.
Neither the name of the OWASP Foundation nor the names of its contributors may be used to endorse or
Progress Rollbase Private Cloud v4.5 incorporates ThreeTen backport v1.3.2. This technology is subject to
the following terms and conditions:
Copyright (c) 2007-present, Stephen Colebourne & Michael Nascimento Santos All rights reserved.
disclaimer.
Neither the name of JSR-310 nor the names of its contributors may be used to endorse or promote products

Progress Rollbase Private Cloud v4.5 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.
* 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
* 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.
OF MERCHANT ABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT
Progress Rollbase Private Cloud v4.5 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.
- 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
- Neither the name of Sun Microsystems nor the names of its contributors may be used to endorse or promote

Progress Rollbase Private Cloud v4.5 incorporates OWASP Foundation Java Encoder v1.2. This technology
is subject to the following terms and conditions:
Copyright (c) 2015 OWASP. All rights reserved.
* 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
* Neither the name of the OWASP nor the names of its contributors may be used to endorse or promote products
CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)ARISING IN ANY
Updated:1/29/2018

Rollbase User Guide

Загружено:

Сведения о документе

Оригинальное название

Авторское право

Доступные форматы

Поделиться этим документом

Поделиться или встроить документ

Параметры публикации

Этот документ был вам полезен?

Это неприемлемый материал?

Авторское право:

Доступные форматы

Rollbase User Guide

Загружено:

Авторское право:

Доступные форматы

® ®

Progress Rollbase User's Guide

Chapter 1: Introduction to Progress Rollbase..........................................19

Chapter 2: What's new in this release........................................................57

Rollbase: Progress® Rollbase® User's Guide: Version 4.5 3

What's new in Rollbase 4.2.1..............................................................................................................133

Chapter 3: Designing a Rollbase application..........................................239

Chapter 4: Laying the foundation.............................................................269

4 Rollbase: Progress® Rollbase® User's Guide: Version 4.5

Restricting records for lookup fields.........................................................................................321

Chapter 5: Adding business logic ...........................................................349

Rollbase: Progress® Rollbase® User's Guide: Version 4.5 5

Supported data types and conversions....................................................................................433

Chapter 6: Customizing the user experience..........................................489

6 Rollbase: Progress® Rollbase® User's Guide: Version 4.5

Sorting and grouping................................................................................................................563

Chapter 7: Supporting mobile users........................................................621

Chapter 8: Integrating with outside sources...........................................659

Rollbase: Progress® Rollbase® User's Guide: Version 4.5 7

Migrating the application..........................................................................................................691

Chapter 9: Security and access control...................................................719

Chapter 10: Publishing and distributing applications............................765

8 Rollbase: Progress® Rollbase® User's Guide: Version 4.5

Enabling or disabling Marketplace in Rollbase Private Cloud..................................................771

Chapter 11: Advanced setup and administration....................................791

Chapter 12: Installing and administering Private Cloud........................831

Rollbase: Progress® Rollbase® User's Guide: Version 4.5 9

Private Cloud updates..............................................................................................................834

10 Rollbase: Progress® Rollbase® User's Guide: Version 4.5

Chapter 13: Setup and administration for ISVs.......................................977

Chapter 14: Reference...............................................................................989

Rollbase: Progress® Rollbase® User's Guide: Version 4.5 11

12 Rollbase: Progress® Rollbase® User's Guide: Version 4.5

Rollbase: Progress® Rollbase® User's Guide: Version 4.5 13

14 Rollbase: Progress® Rollbase® User's Guide: Version 4.5

Chapter 15: Getting help .........................................................................1357

Chapter 16: Third-party acknowledgements.........................................1359

Rollbase: Progress® Rollbase® User's Guide: Version 4.5 15

Rollbase Public Cloud Third-party acknowledgements.....................................................................1359

16 Rollbase: Progress® Rollbase® User's Guide: Version 4.5

Rollbase: Progress® Rollbase® User's Guide: Version 4.5 17

18 Rollbase: Progress® Rollbase® User's Guide: Version 4.5

Rollbase: Progress® Rollbase® User's Guide: Version 4.5 19

20 Rollbase: Progress® Rollbase® User's Guide: Version 4.5

Rollbase: Progress® Rollbase® User's Guide: Version 4.5 21

22 Rollbase: Progress® Rollbase® User's Guide: Version 4.5

• Support for affiliates, resellers, and ISVs

• Get started quickly and learn by doing

Rollbase: Progress® Rollbase® User's Guide: Version 4.5 23

For details, see the following topics:

• Supported browsers and platforms

• Basic Rollbase concepts

• Navigating the Rollbase environment

• Learn with hands-on exercises

Supported browsers and platforms

24 Rollbase: Progress® Rollbase® User's Guide: Version 4.5

Updating your profile and logging out

The menu includes the following options:

Selecting and modifying your security questions

Rollbase: Progress® Rollbase® User's Guide: Version 4.5 25

The Switch Tenant dialog opens.

26 Rollbase: Progress® Rollbase® User's Guide: Version 4.5

You are now logged in to the other tenant.