This document

• This document is a guide to “RapidApp” - the low-code part of CaptainCasa.

• Video tutorials

  • There are series of tutorial videos available, please check our web site https://www.CaptainCasa.org - we strongly recommend to use these tutorials in addition to this document.

Concepts

Different levels of individualization

Applications consist out of parts, that are “always the same” throughout different types of applications. Example:

• The user has to logon.

• The user hat to start a workplace to start functions from.

• There is a set of entities within the database that you need to edit, export/import, transfer between systems. The user can edit these entities by corresponding forms, there are validations on the logic side to ensure the integrity of data.

And applications consist out of parts that are individual for a specific application.

Some of these specific parts are add-ons to the standard parts:

• You want to add own, specific validation rules to your entities.

• You want to add additional information into forms. You want to change the sequence of user interface interactions.

Other parts are completely decoupled from standards - and are individually designed. Example:

• You want to have a special dashboard for managing production orders - in order to drag/drop them onto machines or persons to execute them. You want alarms from production to be immediately shown in a visualization of a production line.

What you normally would do...

Assuming you have all resources available you typically would follow a strategy like this one:

• For the standard parts you would use dedicated developers in order to build a flexible framework, that can be parameterized for the concrete application use case. The framework should provide corresponding tools to customize these use cases in a simple, fast way.

The framework should allow to be extended to a certain level - in order to bring in own processing or visualization rules.

• Typical individual extensions then require defined anchor points in which the extensions can be applied. There should be some strong guidance how to use these extension points.

For the decoupled, individual parts of the application you would not try to abuse the standard parts so that you force everything into it! You would allow to just “develop” - based on a solid, efficient environment.

The borders between what is standard level, what is extension level and what is individual level are not define-able in a fix way. So you would never follow a strategy to implement these levels in different technologies. - But you would prefer to have a consistent technology and architecture that is used for all of these levels - so that knowledge can be shared across the levels and so that deployment and runtime behavior remains consistent.

...and what CaptainCasa RapidApp is doing!

Well, this is exactly what CaptainCasa RapidApp is doing! Defining one consistent implementation infrastructure based on

• Java as implementation language/environment

• Relational databases for storing data

• CaptainCasa Enterprise Client as Java-based Web-Frontend

• Docker as base for runtime deployments

“No-code” for the standard parts!

There are a couple of default issues coming with any application project that you just can set up by definition, without any coding. What you get is:

• You get a very quick start up phase of your application project “by one click” - including a setup of a design time environment and runtime environment. The runtime environment already contains “all you need” - from the user interface down to the database.

• You get a very fast, no-code definition of entities - and all issues involved:

  • the automated creation and update of database, the scripts for SQL creation of tables

  • the REST APIs for exporting and importing data

  • The list and detail screens to edit the data - that can be individually created by dragging and dropping controls

  • The basic functions on view and logical level to add individual validations and processing

  • The protocol of changes of entity instances when users create, change of delete them

• Entities can be simple entities (one data structure) or complex entities (hierarchically structured entities, e.g. header-item structure). Entities can reference one another, coming with automatically followed integrity rules on the logical side and corresponding controls (e.g. selection controls) on the view side.

• You get a no-code workplace management for the users of your application that includes

  • Logon, user verification, password reset by mail

  • Setting of basic texts, colors, logos, images

  • Individual, role-based function collections for different types of users

• You get a no-code authority management that controls access of users to entities and to workplace functions

“Low-code”-Java for enriching the default!

The default lets you define simple and complex entities which already cover many types of integrity rules for processing and validating entity objects. But you may add:

• Specific consistency rules that are to be expressed by concrete procedural logic.

• Specific interfaces that you may include when editing and saving data.

• Specific add-ons in the user interface to integrate additional information and additional functions into the user dialog.

All this can be done by predefined, easy to follow extensions for enriching the default. The base classes to apply the extensions to are already created by the default processing - so you have clear entry points to add additional logic.

Extensions are created using “guided Java” as language. This includes:

• Clear entrance points where to apply the extensions.

• Super-simple, integrated SQL access to all entities.

• Automatic integration into architectural concepts (e.g. separation of logic from view, transaction management, concurrency management, ...)

“Any”-Java for free-style development!

The “No-code” and “Low-code” parts address these issues which are “common standard”: User-management, workplace management, entity management, sophisticated form management on persistent data.

What's about the issues which are not standardized?

Examples:

• Complex interfaces to other systems?

• Complex user interfaces that are not form-oriented but highly interactive? E.g. scheduling and assignment of orders to employees and machines with drag & drop?

Here you use “normal Java” together with the normal CaptainCasa Enterprise Client which directly binds user interface processing to Java without any client-side development.

Advantages

Structural/ architectural advantages

You application follows one architectural structure:

• A pure Java-based architecture behind all layers

• A easy, extendable user interface using the CaptainCasa Enterprise Client as core framework

• Simple to use, integrated concepts for the defaults: database access, authorization management, REST services, ...

• A simple runtime management of your application based on Docker-based deployment.

Project advantages

You project will jump-start because the skeleton of the application is visible immediately: the workplace, the entities, the forms to edit these entities.

Your project team does not have to burn development resources for “stupid issues” - e.g. lists of data, selection of an data item, open up detail dialog to edit and save the data... These issues come out of the box and can be customized without Java coding.

Your project team can directly focus on these things which matter: the individual issues, that make your application and that add value to your application.

Inside your project team you can split up resources according to the different individualization levels:

• Forms and basic rules can be customized by non-Java-developers

• Extensions can be added by Java-”newbies”

• Individual implementations can be added by “real” Java-developers

Installation

Two installation steps

• Logon to CaptainCasa download page

  • https://captaincasa.org/download

• Download from the “Jakarta EE” section

  • (1) The latest environment (“Step 1”)

  • (2) The CaptainCasa Installation (“Step 2”)

• (1) only contains environment components, such as

  • Java SDK (Open Java based)

  • Tomcat

  • Maven

• (2) contains the CaptainCasa demos and tools

• Install the files one after the next

  • All setups will be using the same installation directory - each setup adding its specific parts to this directory

• Please note

  • In case of updating the CaptainCasa version later on, you only have to update the CaptainCasa Installation - and leave the environment components as they are

Starting the server and the tools

• In the installation directory you will find certain command files

  • A_startserver => starts the “application” server (default port 50000). By default it contains the CaptainCasa Demo Workplace. It's also the server that will be used for deploying your applications later on. This is the server with the green background by default.

  • B_startclientRISC_demos => opens the URL (http://localhost:50000/demos/index.html) of the Demo Workplace in your brwoser

  • C1_starttoolsserver => starts the “tools” server (default port 51000). This is the server with the red background by default.

  • C2_starttoolsRISC => opens the URL (http://localhost:51000/editor/indexRISC.html) of the CaptainCasa tool set

• Please note

  • There is a variant “A_startserver_debug”: this will start the server in debug mode so that you may debug it by using remote debugging via port 50010. There is no significant performance implication if no debugger is attached, so you may also use this variant when getting into Java development issues later on.

Creating your first RapidApp project

Video tutorials

• In parallel to this documentation there is a set of video tutorials available.

  • https://captaincasa.org/first-steps - section “RapidApp”

Create project

• From the CaptainCasa Tool Set start from the menu

  • “File” => “New Project” => “RapidApp! project”

• In the dialog that shows up define...

  • The group id

  • The artifact id

  • The directory in which your project will be created as sub-directory

  • You may decide between different project types (e.g. with/without Spring Boot inclusion) - select the most basic one at the beginning, it's no problem to change afterwards.

• Both group id and artifact id are “commonly used” ids in the area of Maven projects. The “group id” identifies the organization in which the project is created, the “artifact id” is actual the project name within this organization. The artifact id is also the one that defines the name of the project directory by default.

  • You may start with “test” as organization id but should switch to something more serious later on.

  • The group id may contain dots (“.”). So you may define “com.xxx.yyy” as organization. The group id then is transferred into corresponding Java package names.

Create & configure the database

• By default a Hypersonic SQL database is used (HSQL). Hypersonic SQL is a sophisticated database directly running in the Java virtual machine of the application.

  • This means: you do not have to care about the database at all during development - the database is part of the server.

  • The configuration can be viewed in the “Configuration” tab (“RapidApp!” section at the bottom):

db_url=jdbc:hsqldb:file:./data/...nameOfProject...

db_driver=org.hsqldb.jdbc.JDBCDriver

db_username=SA

db_password=

db_sqldialect=hsqldb

db_autotrim=true

db_withpooling=true

• We recommend first to stay with the Hypersonic SQL database. If you later on want to use some other database during development, e.g. PostgreSQL, you can easily switch. - Example:

  • Create a PostgreSQL database for this project

    • We recommend to use the artifact id of your project as name for this database

    • You may create the database within some explicit installed version of PostgreSQL - or you may start PostgreSQL as Docker container.

  • Configure the database access from your application

    • In the CaptainCasa tool set open “Configuration” and navigate to the “RapidApp!” section at the bottom

    • Open the “Configuration” there and define the parameters

db_url=jdbc:postgresql://localhost:<yourPort>/<yourDB>

db_driver=org.postgresql.Driver

db_username=yourPostgresUser

db_password=yourPostgresPassword

db_sqldialect=postgres
db_autotrim=true

db_withpooling=true

• • Check the documentation https://www.captaincasa.com/docu/eclnt_ccee/ for more details and options on configuring the database. - You may later on e.g. outsource all parameters (especially “username” and “password”) and completely define all parameters by using a defined Java API.

Define your first content

• Base of your application is a meta data definition holding

  • Entities with their properties

  • Data types

  • References

  • Authorization objects

• This meta data is kept in resource file “ccda_metadata.xml” of your project

  • File name is: <project>/main/resources/ccda_metadata.xml”

• The file can be edited manually but we strongly recommend to use the tool set of CaptainCasa for editing

Define the first entity “article”

• Open the “RapidApp!” tab and select “Edit meta data”

  • The meta data editor will show up in the center of the tool set

• Create entity “article”

  • Select “Create new”

  • Define id “article”, text “Article”

• Create properties

  • Add properties via “Create new”

  • For each property define id, text, data type + additional information

  • At least one property must be marked as “key property”

  • The list of data types is derived from default projects that your project automatically includes - you may add own data types by navigating into the “Data types” tab

• Example for property definitions for entity “article”:

<property id="id" text="Id" dataType="ccda_base.idString50" key="true"/>

<property id="description" text="Description" dataType="ccda_base.textLong500"/>

<property id="name" text="Name" dataType="ccda_base.textShort100" mandatory="true"/>

• Save the meta data

  • In case of errors: follow the corresponding messages that are shown on the bottom

Generate and deploy

• Press “Generate”

  • Based on your meta data certain Java classes are generated and added to your project, examples:

    • A “Pojo” class for your entity

    • A controller class for your application logic processing

    • A detail UI class with layout definition

    • A list UI class with layout definition

  • After generation the project is rebuild by internally starting a Maven build

    • The output of this build is shown as dialog

• Press “Deploy”

  • This will no deploy the current status of the project to the Tomcat that is the “application” server (the “green” one)

• The list of entities within the left “RapidApp!” tab now shows the new entity “Article”

Build your list UI

• The list UI is showing the entity instances that are stored in the database. From the list you can navigate (double click) into the detail editor of the entity.

• Create the list UI in the following way:

  • In the “RapidApp!”-tree on the left open the popup menu on the entity “article” that you just created. Select ”Open list dialog”.

  • The layout editor will be opened in the center

    • Press “Refresh preview”

    • Click into the content area of the previewed dialog

  • From the tree “on the left” drag the properties that you want to include in the list and drop them into the control “tdap:beangridwitheditor”.

    • Pay attention: the drag&drop must me executed on top of the component-icon on the right side within the tree node

  • Press “Refresh preview” or “Save” to update the preview.

  • The preview is the live preview of your system - it's not a simulated preview!

  • Your application is deployed in the Tomcat which is started with “A_startserver.bat”. You may take a look into your installation's Tomcat directory:

<...installDir...>/server/tomcat/webapps/<...yourApplication...>

Build your detail UI

• The detail UI is showing one instance of the entity. The dialog is used for creating, editing or viewing the instance.

• Create the detail UI in the following way:

  • In the “RapidApp!”-tree on the left open popup menu for the entity “article” and now select “Open detail dialog”

  • Press “Refresh preview”

  • Click into the content area of the previewed dialog

  • Now drag the properties on the left (again using the images shown in the tree node) an drop them into the layout.

    • In the tree there are two images: one for dragging the corresponding control only (e.g. the “t:field”), the other one for dragging the corresponding control embedded into a container row (“t:row”).

  • Press “Refresh preview” or “Save” to update the preview.

Test the whole scenario

• Go b    ack to the list of articles that you created.

• Press “Refresh preview”

• In the dialog you now can test your entity - and create new ones and edit existing ones

Setting up “link” relations

• “Link” relations are relations in which one property of the one entity points to another object (typically an other entity)

• By following this relation...

  • the user receives a list of valid values during input

  • the logic may automatically validate the data input

• During an object update the linked object is referenced but not part of the update process itself.

Meta data

• A property of an entity might point to another entity

  • Example: in the entity “article” you might add a property “unitOfMeasureId” which should point to an instance of entity “unitOfMeasure”.

  • The entity “unitOfMeasure” might be defined as follows:

<entity id="unitOfMeasure" isPublic="true" text="Unit of measure">

    <property dataType="idUnitOfMeasure" id="id" key="true" mandatory="false" text="Id"/>

    <property dataType="ccda_base.textShort100" id="name" mandatory="true" text="Name"/>

</entity>

• For the entity that you point to (“unitOfMeasure”) you need to define a reference.

  • Open the “References” tab in the Meta Data Editor”

  • Create a reference e.g. with id “refUnitOfMeasure”

    • Select the key property of the “unitOfMeasure” as “value” and some other property as “text”

<reference id="refUnitOfMeasure" isPublic="true" refEntity="unitOfMeasure" refIdColumn="id" refTextColumn="name" text="Ref to unit of measure"/>

• From the property of the referencing entity (“article-unitOfMeasureId”) you now can define the reference correspondingly

  • In the “Processing” section of the property there is a flag “Check against valid values at runtime”. If you set the value of this flag to “true” then the reference will be part of the logical consistency check of the entity: values that the user defines are checked against the valid values of the reference. If you do not defines this flag as “true” then the reference values will be treated as proposal but will not be part of the consistency check.

<entity id="article" isPublic="true" text="Article">

    <property dataType="idUnitOfMeasure" id="unitOfMeasureId" mandatory="false" propertyReferenceId="refUnitOfMeasure" text="Base unit of measure" validateByValidValues="true"/>

</entity>

• “Generate” and “Deploy” the meta data.

UI processing

• Edit the layouts for the “article” entity:

  • In the detail UI now automatically a “t:combofield” control will be used when dragging/dropping the property into the layout.

    • The “t:combofield” will open up a value selection dialog which queries its data from the “unitOfMeasure” entity

  • For the list UI you will now see that there are two drag possibilities in the tree on the left: one for dragging the actual value (property “unitOfMeasureId”, one for dragging the text of the reference.

Setting up “embedded” relations

• “Embedded” relations are relations in which one object is the owner of either one other object or a list of other objects. The embedded object instance is exclusively owned by the embedding object instance.

  • Embedded objects are part of the update processing of the embedding object. They are always accessed and updated as part of the embedding object.

  • Examples

    • An “order” entity embeds “order items”.

    • A “person” entity embeds an “address”.

• On property level the embedding object provides one (or more) properties which are shared with the embedded object

  • Examples

    • The “order” has an “id”, the “order item” has an “orderId” and an “itemNumber” - the “id” of the “order” is shared with the “orderId” of the “order item”

order:        orderId              || ... | ... | ...

order item:   orderId | itemNumber || ... | ...

• • • The “person” has an “addressId” that is automatically generated (e.g. a UUID or a counted int) - which is the key of the “address” entity. The “address” entity is a generic definition of an address which can be embedded into multiple other entities (e.g. “person”, “customer”, “supplier”, “company”, ...)

person:      personId || ... | ...| ...| addressId | ...

address:     addressId || ... | ... | ...

Meta Data

• Define the embedded entity in the “Embedded entities” tab of an entity

• Select the embedded entity and define the type of embedding (“LIST” for 1:n/ “OBJECT” for 1:1)

• By default select “Create if not exists” so that the sub-object is automatically created when creating the embedding object

• Define the property mapping so that the runtime knows how to find the embedded object for an embedding object

  • On the right side of the key mapping you select the properties of the embedded entity, on the left side you select the corresponding property of the embedding entity

• Examples

  • The “order item”-”orderId” is mapped to the “order”-”id”

  • The “address”-”id” is mapped to the “person”-”addressId”

• Define if you want the embedded object to be part of the view that is used to show the list of embedded objects. Typically you do so for embedded objects with a 1:1 reltionship (“instance”).

  • In case of “list” relations you need to in addition define the value for the additional key properties so that the view will exactly select one object from the list of objects.

  • You can define the value of such property as “system parameter” (e.g. the current language of the user session) or as fix value.

UI layer

• Embedded Object level

  • For each embedded object you define a “Detail dialog”

  • For “list”-embedded objects you define a “Grid editor dialog” - in this dialog the list of embedded objects is shown + the user can create/remove instances. When clicking an item of the list then the “Detail dialog” is shown below the list.

• Embedding Object level

  • In the embedding object you can drag/drop the detail dialog (“instance”) or the grid editor (“list”)

Basic meta data definitions

Entity

• An entity is the definition of an object type.

• The definition includes:

  • Definition of properties (“fields”)

  • Definition of embedded object types. An embedded object is a sub-part of the entity object. Logical processing is always managed through the entity object which includes the embedded object into its processing.

    • Examples

      • The object type “order” may contain “order items”

      • The object type “customer” may contain an “address”

  • Do not mix “embedding” with “referencing”! Referencing another entity does not mean that the entity owns the other entity!

    • Example

      • The object type “order” may reference an object type “customer” - but doe not own it.

Data type

• When defining a property for an entity you have to define the data type for the property. The data type consists out of:

  • The general type (“String”, “int”, ...)

  • Specific definitions that depend on the general type. Example:

    • For “String”: the maximum length

    • For “BigDecimal”: the number of digits before and after the decimal separator

• By using data types, the definition of data fields is structured: instead of everyone defining e.g. own text fields with different maximum length, you define one central data type “description” and e.g. assign a length of 500 - which then is applied by all users of data type “description”.

Reference

• References are definitions which tell how the values of a property references to existing values

  • References are defined in several ways

    • Reference to an entity (you may compare these ones with “foreign key” definitions)

    • Reference to a property file in which the values are stored

    • Reference to a Java class implementing a certain interface (“IValidValuesProvider”)

  • The reference not only contains the definition how to get the values but also contains optical definitions that influence the way the valid values which are behind the reference are presented

• References can be are assigned on property level

  • Example: the property “customerId” of entity “order” references a reference “refCustomer” which itself is defined as reference to the entity “customer”

  • You may decide if a reference is to be used as part of the validation of an object - or if it is used as proposal value only.

Authorization

• At certain places within the application processing the application may want to check if the currently logged on user is authorized to perform the corresponding activity

• For this reason the application defines an authorization object type. The definition includes:

  • The id and name of the authorization object type

  • The parameters that are passed in order to describe the issue to check

• Example

  • Within the editing of entities CaptainCasa defined the following autorization object type:

    • Id: “CCEntityRights”

    • Parameters

      • “entity” - Id of entity for which an edit-activity is started

      • “action” - Type of activity (“CREATE/EDIT/DISPLAY”)

• RapidApp creates ab Authorization request class out of this definition:

package org.eclnt.dataapp.logic.authority;

import org.eclnt.dataapp.logic.authorization.*;

public class ARCCEntityRights

    extends AuthorizationRequest

{

    public static final String TYPE_ID = "eclnt_dataapp.CCEntityRights";

    public static final String ASPECT_entity = "entity";

    public static final String ASPECT_action = "action";

    public ARCCEntityRights()

    {

        super(TYPE_ID);

    }

    public ARCCEntityRights setEntity(Object value) { addAspectValue(ASPECT_entity,value); return this; }

    public ARCCEntityRights setAction(Object value) { addAspectValue(ASPECT_action,value); return this; }

}

• At runtime this class can be used as follows:

ARCCEntityRights r = new ARCCEntityRights()

    .setAction(ENUMEditMode.EDIT)

    .setEntity(BCIRuntime.instance().getEntityIdByClass(selectedObject.getClass()));

boolean authorized = AuthorizationManager.instance().checkIfUserIsAuthorized(r);

• The implementation of the AuthorizationManager is done by an implementation behin the interface IAuthorizationManager - there is a default implementation which is part of the “ccda_base” project, that by default is included in any RapidApp project.

  • The setup of this default authorization manager is part of the runtime workplace

Public page beans

• A page bean is the class of a dialog

  • Examples

    • All dialogs you create for entities (e.g. the list showing the saved entity instances) are represented by a corresponding page bean

• By adding a page bean class as public page bean, the corresponding dialog can be referenced e.g. when configuring the user workplace

Applying own logic

Importing the project

• You may use any Java development environment

  • Eclipse, NetBeans, IntelliJ, VS Code, ...

• The RapidApp project is a plain Maven project.

  • Use the IDE's import functions to import the RapdiApp project as Maven project correspondingly.

  • Example, Eclipse: Call “File > Import... > Maven > Existing Maven Projects”.

• We strongly recommend to use UTF-8 as default character set that is used within the project.

  • All tool functions of CaptainCasa read and write textual information using UTF-8.

Generation of artifacts

Why at all?

• Couldn't the whole application be built without any generation?

  • Yes, of course - a generic applications framework could e.g. be completely based on dynamic data structures (e.g. hash tables), so that no generation is required at all.

• But: we decided to go the “generation way” for the following reasons

  • We believe that at a certain detail level you want to be able to easily step in and add own (Java) implementations. Here you want to use concrete classes that are meaningful to you - and that ensure data type consistency.

  • Example: an entity should be reflected by a corresponding data object (“Pojo-object”) in which each property is represented by a setter/getter-combination

  • By generating the essential classes for an entity on all layers (view, controller, data) we provide simple to use, extendable entrance points to plug own coding. The system provides a generated skeleton, which is the structured base for own implementations.

Separation between generated code and own code

• For all classes besides the data object class itself there are two generated classes

  • A “generated” parent class (with extension “_generated”)

  • The “actual” class which extends the generated parent class

• As result code that you add in the “actual” class is strongly decoupled from the code that is generated.

  • In case of re-generations only the “generated” parent class is re-generated, the code of the “actual” class remains untouched.

Adding own validation logic

• Validation logic is part of the controller class

• Naming convention: for entity “person” the name of the class is “PersonController”

• In this class the main methods to potentially override are

  • synchronize(...)

  • validate(...)

Adding own view elements / logic

• You can freely update the dialogs (e.g. detail dialog) and add own logic

• For each dialog there is a

  • XML layout definition (e.g. PersonDetail.xml) for entity “person”

  • Java class (e.g. PersonDetail.java) for entity “person”, which extends “PersonDetail_generated.java”

  • In the classes you can access the currently edited object(s)

  • Please check the JavaDoc for detailed information

• Use just normal CaptainCasa development principles.

Data object and Data context

• For each entity there are two classes that are generated

  • (1) the data object (“pojo” object) which is a 1:1 representation of the entity property structure.

    • Naming: “DOPerson” for entity “person”

  • (2) the data context which contains the data object (“home object”) together with its embedded relations.

    • Naming “DCPerson” for entity “person”

    • For each embedded relations the data context object contains corresponding set/get methods. If the embedded relation is of type “List” (1:n) then there are additional add/remove methods.

• Purpose of the data context

  • being the instance to keep an object with its embedded objects that is shared between various processing parts of the application

  • lazy loading of the embedded relations

  • tracking changes in its contained objects

  • central data instance to consistently update/save an object together with its embedded objects

• Example on data context

  • An “order” has a list of embedded “order items”

  • Various parts of the program now operate on this order during its creation/update. By passing the data context instance (“DCOrder” instance) into these parts all parts now can see and update all data aspects of the order. All parts of the application operate on the same object instances - both for the order itself and for the order items.

Setting up the user workplace

Basics

• The workplace contains

  • a log-in

  • some basic layout of log-in and subsequent pages

  • a function tree and a working area from which functions are started

Opening the workplace

• You may open the application workplace directly from the tool set

  • RapidApp tab > Runtime > Open workplace

  • When opening without logon then the user “undefined” is internally used

• You may copy the URLs that are shown after opening the workplace from the browser and directly use them to start the workplace without going through the tool set

Defining the function tree

Functions trees

• There are two types

  • Design time functions trees - these are the ones that are defined / pre-configured by the application. They are delivered as part of the application (resource file) and can be directly assigned to users.

  • Run time function trees - these are function trees that you can individually set up in the database. You may create a specific function tree which exactly represents the collection of start-able functions and the order of functions that you want.

Design time functions trees

• These are the functions trees that come pre-configured with the application

• Each application has one or several function trees in which all applications functions are listed

  • There is a default function tree “default”

  • But you may create additional function trees.

• The definition is done by using the CaptainCasa toolset

  • Tools > Edit existing workplace function tree > default opens up a function tree editor. In the menu you may also create additional functions trees and edit them.

  • In the editor you defined the nodes of the tree. A node either is a folder node or is defined to include a definition of a dialog to be started.

• You can open the application function tree from the tool set

  • RapidApp tab > Runtime > Open workplace

Storing of design time functions trees

• The definition of the function tree is an XML file

  • src/main/resources/bcigen/<appName>/ccworkplace/functiontrees/<nameOfFunctionTree>.xml

  • Example for tuto1 project:     src/main/resources/bcigen/tuto1/ccworkplace/functiontrees/default.xml

• The format is an XML file:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<workplaceFunctionTreeInfoNode>
   <folderOpened>false</folderOpened>
   <subNodes>
       <text>My application</text>
       <folderOpened>true</folderOpened>
       <subNodes>
           <text>Flexible analysis</text>
           <folderOpened>true</folderOpened>
           <subNodes>
               <text>Prompting</text>
               <folderOpened>false</folderOpened>
               <workpageStartInfo>
                   <pageBeanName>org.eclnt.ccda_base.view.CCAppPrompting</pageBeanName>
                   <id>org.eclnt.ccda_base.view.CCAppPrompting</id>
                   <openMultipleInstances>true</openMultipleInstances>
                   <decorated>true</decorated>
                   <popupSupported>false</popupSupported>
                   <closeSupported>true</closeSupported>
                   <openAsPopupByDefault>false</openAsPopupByDefault>
                   <excludeFromSavePerspective>false</excludeFromSavePerspective>
                   <paramMap/>
                   <sortIndex>-1</sortIndex>
               </workpageStartInfo>
           </subNodes>
       </subNodes>
       <subNodes>
           <text>Order Management</text>
           <folderOpened>true</folderOpened>
           <subNodes>
               <text>#{rr.tuto1['VIEW.test.tuto1.view.dialogs.OrderList']}</text>
               <folderOpened>false</folderOpened>
               <workpageStartInfo>
                   <pageBeanName>OrderList</pageBeanName>
                   <id>OrderList</id>
                   <openMultipleInstances>false</openMultipleInstances>
                   <decorated>true</decorated>
                   <popupSupported>false</popupSupported>
                   <closeSupported>true</closeSupported>
                   <openAsPopupByDefault>false</openAsPopupByDefault>
                   <excludeFromSavePerspective>false</excludeFromSavePerspective>
                   <paramMap/>
                   <sortIndex>-1</sortIndex>
               </workpageStartInfo>
           </subNodes>
       </subNodes>
       <subNodes>
           <text>Master data</text>
           <folderOpened>true</folderOpened>
           <subNodes>
               <text>#{rr.tuto1['VIEW.test.tuto1.view.dialogs.ArticleList']}</text>
               <folderOpened>false</folderOpened>
               <workpageStartInfo>
                   <pageBeanName>ArticleList</pageBeanName>
                   <id>ArticleList</id>
                   <openMultipleInstances>false</openMultipleInstances>
                   <decorated>true</decorated>
                   <popupSupported>false</popupSupported>
                   <closeSupported>true</closeSupported>
                   <openAsPopupByDefault>false</openAsPopupByDefault>
                   <excludeFromSavePerspective>false</excludeFromSavePerspective>
                   <paramMap/>
                   <sortIndex>-1</sortIndex>
               </workpageStartInfo>
           </subNodes>
           <subNodes>
               <text>#{rr.tuto1['VIEW.test.tuto1.view.dialogs.PriceListList']}</text>
               <folderOpened>false</folderOpened>
               <workpageStartInfo>
                   <pageBeanName>PriceListList</pageBeanName>
                   <id>PriceListList</id>
                   <openMultipleInstances>false</openMultipleInstances>
                   <decorated>true</decorated>
                   <popupSupported>false</popupSupported>
                   <closeSupported>true</closeSupported>
                   <openAsPopupByDefault>false</openAsPopupByDefault>
                   <excludeFromSavePerspective>false</excludeFromSavePerspective>
                   <paramMap/>
                   <sortIndex>-1</sortIndex>
               </workpageStartInfo>
           </subNodes>
           <subNodes>
               <text>#{rr.tuto1['VIEW.test.tuto1.view.dialogs.CustomerList']}</text>
               <folderOpened>false</folderOpened>
               <workpageStartInfo>
                   <pageBeanName>CustomerList</pageBeanName>
                   <id>CustomerList</id>
                   <openMultipleInstances>false</openMultipleInstances>
                   <decorated>true</decorated>
                   <popupSupported>false</popupSupported>
                   <closeSupported>true</closeSupported>
                   <openAsPopupByDefault>false</openAsPopupByDefault>
                   <excludeFromSavePerspective>false</excludeFromSavePerspective>
                   <paramMap/>
                   <sortIndex>-1</sortIndex>
               </workpageStartInfo>
           </subNodes>
       </subNodes>
   </subNodes>
</workplaceFunctionTreeInfoNode>

• Explanation of core structure

  • Each node has text

  • In case there is a start-abe functions behind the node (e.g. for leaf nodes) then the node contains a “workpageStartInfo” element

  • Folder nodes have “subNodes” elements

  • In a “workpageStartInfo” element you defin

    • the pageBeanName (the class name of the dialog to be started)

Runtime function trees

• In addition you can define any other function tree in parallel which is stored in the database of the runtime system

• Define by calling from runtime workplace:

  • Base System > Workplace management > Workplaces

  • Here you have the same editor as with the application function tree - the result is stored in the database

  • In the user definition you can assign the Workplace to a user-management

  • Base System > User management > Users => Workplace tab of a user

     

Customization of logon screen and welcome screen

• The workplace contains a default long screen and a default welcome screen. Both can be customized to show own texts and images.

• Customizing is stored in the database. Editing is done by:

  • Base System > Workplace management > Workplace texts

  • In case of image referenced you may upload own images by calling

    • Base System > Media management > Image catalog

  • Each of the images uploaded into the image catalog can be directly used by using path “/<idOfImage>.ccimage”

Authorization Management

Basics

• RapidApp provides a simple to use and flexible authorization management.

• As part of the application meta data you define “Authorization Object Types”. Each object type consists out of

  • an id

  • a descriptive text

  • a list of so called authorization aspects - which you can consider as a list of fields which describe the exact authorization to be checked

• Out of the meta data definition a concrete “AuthorizationRequest” class is generated.

• At runtime, within the logic processing of the application, the application may create instances of this class, define the concrete aspect values and then check if the current user is authorized or not

Authorization Object Types

Example

• Default part of RapidApp contains the following Authorization Object Type definition

<authorizationType id="CCEntityRights" text="Rights on entity">

    <aspect id="entity" text="Entity" aspectReferenceId="refEntityId"/>

    <aspect id="action" text="Type of action: CREATE/EDIT/DISPLAY" aspectReferenceId="refAuthAction"/>

</authorizationType>

• This authorization is e.g. used when the user double clicks an entity instance in the list of entities in order to get into the detail processing.

Generated class

• The generated class looks like:

package org.eclnt.dataapp.logic.authority;

import org.eclnt.dataapp.logic.authorization.*;

public class ARCCEntityRights

    extends AuthorizationRequest

{

    public static final String TYPE_ID = "eclnt_dataapp.CCEntityRights";

    public static final String ASPECT_entity = "entity";

    public static final String ASPECT_action = "action";

    public ARCCEntityRights()

    {

        super(TYPE_ID);

    }

    public ARCCEntityRights setEntity(Object value) { addAspectValue(ASPECT_entity,value); return this; }

    public ARCCEntityRights setAction(Object value) { addAspectValue(ASPECT_action,value); return this; }

}

Usage in application processing

• A code that checks in a concrete situation if the user is authorized to execute e.g. a deletion looks like:

protected boolean checkAuthorizationForRemoving(BEANCLASS selectedObject)

{

    ARCCEntityRights r = new ARCCEntityRights()

        .setAction(ENUMEditMode.EDIT)

        .setEntity(BCIRuntime.instance().

                   getEntityIdByClass(selectedObject.getClass()));

    return AuthorizationManager.instance().checkIfUserIsAuthorized(r);

}

• Each aspect that represents the current situation is defined using the corresponding “set”-methods

• “set”-methods can be concatenated for simplified writing

• An instance of interface IAuthorizationManager is picked and used for checking.

Interface IAuthorizationManager

Interface

• The interface IAuthorizationManager is:

package org.eclnt.dataapp.logic.authorization;

public interface IAuthorizationManager

{

    public boolean checkLogon(String user, String password);

    public boolean checkIfUserIsAuthorized(AuthorizationRequest request);

    public void expectThatUserIsAuthorized(AuthorizationRequest request) throws MissingAuthorizationError;

}

• The “check” methods pass back a true/false

• The “expect” method is used for simplified coding: an error is thrown when the authorization is missing for the current user

Implementation

• The implementation of the interface is defined by configuration in file ccee_config.properties

...

dataapp_authorizationmanagerclassname=org.eclnt.ccda_base.logic.authorization.CCDAAuthorizationManager

...

• By default a RapidApp projects starts without the definition of a concrete authorization manager - which means: authoritzation management is swithced off.

• RapidApp comes with a default implementation of the interface.

  • Class name: org.eclnt.ccda_base.logic.authorization.CCDAAuthorizationManager

  • The implementation is part of the “ccdabase” dependency (which is added by default to all projects)

Default implementation of Authorization Manager

Dependencies

• The implementation is part of the “ccdabase” project which is by default part of your RapidApp project

• The corresponding dependncy is:

JEE/javax based projects:

<dependency>

    <groupId>org.eclnt</groupId>

    <artifactId>ccdabase</artifactId>

    <version>${cc.version}</version>

</dependency>

Jakarta based projects:

<dependency>

    <groupId>org.eclnt</groupId>

    <artifactId>ccdabase_jakarta</artifactId>

    <version>${cc.version}</version>

</dependency>

Usage

• The following workplace functions are part of the function tree of application “ccdabase”:

  • 

  • User roles - definition of authorizations for an abstract user role

  • Users - assignment of roles to a concrete user

• Definition of user roles

  • 

  • Per role you define authorizations

  • Each authorization refers to a dedicated Authorization Object Type and describes the aspect values which the user user is authorized for

    • Aspect values may contain wildcards “*”

    • Aspect values may occur multiple times

• Assignment of roles

  • In the “User” management you then can assign a user to one or more roles

  • 

User and Authentication Management

Default User Management

• Users have to be registered in the RapidApp user management.

• Users are used for

  • Logging on by dialog (online authentication), optional

  • Executing functions by API (API authentication), always

• Users are the base for the authorization management.

Online Authentication

• The authentication of a user either comes from outside (e.g. OAuth2, SAML, ...) or is done using the default user management.

• Outside authentication

  • The user is passed through some SSO mechanism.

  • Inside the default user mangement...

    • ...the user has to be defined with flag “Anonymous login” as true

    • ...the password of the user is irrelevant

API Authentication

• All APIs provided by RapidApp are using basic authentication

  • ...i.e. user and password are part of http-header-information

• The password for API authentication is not the user's password but is an API key that you can generate for a user:

  • 

  • For each user you can create one or multiple API keys

  • Each API key has an id and a name - and a key

  • The key is generated by the system one time and is only visible to the user just after creation. You immediately have to copy the key and save in a secure way.

  • Also within RapidApp the key is never stored - it's always a hashed version of the key that is internally managed. For better remembering the key a certain reminder-text is generated in addition.

Upgrading the RapidApp version

Regular updates

• CaptainCasa usually provides one update per week, in which bugs are fixed and functional improvements are added.

• There are two updates

  • Update of your application

  • Update of the toolset

Update of your application

• Update version of project

  • Open the pom.xml within the project directory with a text editor

  • Exchange the value of variable “cc.version” right at the beginning of the file to the version you want to update to and save the file.

    <properties>

        <!-- This is the CaptainCasa version to be used. -->

        <cc.version>20260331</cc.version>

        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>

        <project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>

    </properties>

• Then, in your toolset

  • Open the project

  • Open the RapidApp!-view

  • Press “Generate” so that the project content is regenerated and rebuilt

    • If you are using a Java IDE to manage the project in parallel you can execute the Maven build also from there.

  • Deploy the project into the Tomcat running the application

    • Important: a normal “Deploy” is not sufficient, because the normal “Deploy” only does a straight copy of resources (e.g. .jar libraries) from your project into the runtime (Tomcat) - but does not remove old versions.

• • • You have to execute a “Deploy => Clean & deploy server” - in order to first remove old content and then copy updated content into. Stop the application tomcat before executing the “Clean & Reload”.

Update of your toolset

• An update of the toolset is recommended, so that the tool-set's version is the same as your project's version

  • Stop both the application Tomcat and the toolset Tomcat.

  • CaptainCasa's installation consists out of two steps: 1. some base component, 2. CaptainCasa itself. - You now only have to execute the second step.

Adding RapidPDF

RapidPDF is an additional framework by CaptainCasa which simplifies the creation of PDF documents for business objects.

By adding RapidPDF to RapidApp you can...

• ...directly create PDF forms for entities

• ...directly start the creation of PDF documents from the detail screen of RapidApp dialogs

Extending the pom.xml

Open the pom.xml in the root directory of your project.

JEE projects (“Tomcat 9”)

Add the following dependency to your project dependencies:

        <!-- Printing -->

        <dependency>

            <groupId>org.eclnt</groupId>

            <artifactId>eclntsjrxml</artifactId>

            <version>${cc.version}</version>

        </dependency>

Jakarta EE Projects (“Tomcat 10/11/...”)

Add the following dependency to your project dependencies:

        <!-- Printing -->

        <dependency>

            <groupId>org.eclnt</groupId>

            <artifactId>eclntsjrxml_jakarta</artifactId>

            <version>${cc.version}</version>

        </dependency>

Rebuild and redeploy

After having done the changes:

• Rebuild / Generate your project

• Deploy your project

Defining the print forms

Locate the form definition functions

Open the workplace of your project as administrator: in the “[Admin]” section there is the function tree for the “eclnt_sjrxml” project, that you embedded by having updated your pom.xml:

The most important function there is the “Form editor”.

Editing the form

Information on how to edit the form is available here:

• overview documentation:     
  
  https://www.captaincasa.com/docu/eclnt_sjrxml/

• Video: the playlist on “RapidApp” contains videos about configuration print forms inside RapidApp:     
  
  https://www.youtube.com/playlist?list=PLlEgDxNnKfBrwNU4onZdlf66B1jUNERju

Combining projects

Each project builds its “.jar” artifact

The build of a project is executed by the usage of Maven. Maven uses the “pom.xml” file of the project to execute all build steps. The steps by default include:

• The creation of a “.war” artifact

  • This is the file containing all information so that your project can be deployed into a servlet container of your choice (e.g. Tomcat, Jetty, and JEE/Jakarta-Server)

• The creation of a “.jar” articact

  • This is the file that contains the project information so that it can be added into other projects

You may take a look into the “/target” folder of your project in order to view both files.

The “.jar” file is the one that is used for structuring projects. By simple Maven-dependency you can take over all information of one project into another project.

Example: CaptainCasa default projects “ccdabase” and “ccdaclog”

CaptainCasa uses exactly the “.jar”-structuring to by default provide two projects and add them to your project. The Maven-dependencies are:

<dependency>

    <groupId>org.eclnt</groupId>

    <artifactId>ccdabase_jakarta</artifactId>

    <version>${cc.version}</version>

</dependency>

<dependency>

    <groupId>org.eclnt</groupId>

    <artifactId>ccdaclog_jakarta</artifactId>

    <version>${cc.version}</version>

</dependency>

(For JEE projects: use names without “_jakarta”.)

• “ccdabase” - this project comes with default implementations and default entity definitions

  • User and authority management

  • Workplace management

  • Multi language management

• “ccdaclog” - this project contains a default implementation of the change log management, which logs any changes to entity instances in a detailed way.

  • Result: you can trace changes to data

We recommend to keep these dependencies. The id of all CaptainCasa entity types are starting with “CC” - which is treated as reserved name space.

Referencing entity types and other artifacts

• In the meta data management (i.e. file “ccda_metadata.xml” and the tooling the manages the file) artifacts of included projects are always referenced by the id “<projectId>.<artifactId>”.

  • This means: ids always have to be unique within the context of their defining project only. Between projects the project-id is always prepended.