OS.bee Documentation for Designer

OS.bee Documentation for Designer

Here are frequently asked questions from designers which are not mentioned by other Documentation. In this Page, you could find the answer to your question.

Get Started

Pitfalls with new Eclipse installations

Be aware that when installing a new Eclipse environment to look at the preferences for DS Annotations and check the box "Generate descriptors from annotated sources" as OS.bee makes heavy use of automatically generated component descriptors in the OSGI-INF directory. It is unchecked by default for incomprehensible reasons.

Don't forget to set your target platform correctly as described in the installation guide.

Eclipse Installation / Installation SWF / New Project from GIT

Question:

Using Eclispe Neon, execution of Installation Software-Factory as described in the Installation notes, Connect to a GIT Archiv, After Building Workspace the application is not valid (see Screen-Shot) Try to clean the Project was not successful.

Answer:

The version of the installed Software Factory and the version needed for the project do not match.

Please install the appropriate Software Factory version.

cvs2app - question regarding ENUM types

Question:

cvs2app is mentioned in the documentation "App up in 5 minutes" and gives the possibility to create one app directly out of the csv file. One of the first steps is to create an entity, which is generated based on the information on the first line (which contains the column names). In consequence I have 2 questions regarding ENUMS:

• Is it possible to create an entity ENUM out the csv - FILE?

• Is it possible to use an existing ENUM entity during the creation of the app?

For example:

in the entity there is already a definition:

 enum type_ps {
            PROCESS_DESCRIPTION, ORGANISATIONAL
}

and the csvfile looks as follows:

ticket_type_number;ticket_type_description;ticket_type_ps_type
1;CRS handling;PROCESS_DESCRIPTION
2;Administrative;ORGANISATIONAL
3;Delivery package;ORGANISATIONAL
4;Software behaviour;PROCESS_DESCRIPTION

Answer:

Yes it is possible. When using the latest version (from feb 2018), it is possible to supply various meta-information to each column. One meta-info is the hint to the application builder that this column is meant to be a ENUM. By default it wouldn't be possible to guess that fact.

Launch Application from Eclipse (very slow)

Question:

When starting the Application from within the Eclipse it took very long time until the application is up. Are there some settings to be controlled?

Answer:

If you experience very slow performance with Eclipse itself as well as the application you launch from Eclipse it might be a good idea to check the virus scanner you have installed. Some virus scanners check all the files inside the Eclipse installation directory, the Eclipse workspace and the GIT repository which might lead to extreme slow performance. Ask your Administrator how to avoid this.

Structure of the documentation page

In the OS.bee Software Factory Documentation page, there are 3 Headlines used to structure the page:

1. OS.bee DSL Documentation
2. Other OS.bee-Specific Solutions
3. OS.bee Third-Party Software Solutions

At the end of Chapter one there are some helpful hints to work with eclipse. To start with Eclipse and the SWF these hints could be very useful.

• One more hint: to Use STRG-Shift-O to organize the import inside the DSL.

Modeling

Display of article description

Question:

I would like to match the article number to the name of the article on a dialog box (field is not editable). The grammar of the dialogue gives me little meaningful ways to specify fields. The "autowire" and "view" probably do not help here - the manual does not help me any further.

One more example to make it clearer: A GTIN is scanned - the GTIN appears in the GTIN field and the article description in the Label field, the unit of measure in the Unit of measure field

Answer:

I assume you mean the descriptor of a relation of cardinality many to one in a combo box. For the time being the entries in the combo box are identical with the one which is selected and therefore do not show more information as in the list. If the domainKey or domainDescription keyword at the owner entity of the many to one relationship decorates a certain attribute, this one will be the displayed value in the relationship-combo. As the displayed value is not important for the linking or unlinking of a relationship, but its underlying related datatype, you can also use a synthetic attribute as domainKey attribute. You could create a new attribute in the owner entity combining number and name. In the authorization DSL you could declare it invisible. Let it automatically be combined with a def statement in entity model.

In autobinding, there is no solution for this right now. In the ui dsl you can add bindings as desired. A solution could be the following: we introduce a modifyer (metaflag) to mark an entity attribute which is unexpessive (such as GTIN or item number or sku) without additional information. If the autobinding mechanism detects such an attribute it automatically adds the domainKey and/or domainDescription to the right of the unexpressive attribute. If the marked attribute itself is either a domainKey or domainDescription the respective missing part is added.

Please try the following solution for the number + description problem: create on the one side of a many to one relationship a domainKey attribute where you combine 2 or more attributed virtually. E.g. you name the attribute "productSearch". Then you create a method with the "def" keyword with a preceding annotation "@PostLoad". The effect is that whenever you load the domainKey, the system will call the annotated method and assign whatever you put inside the method to this domainKey attribute. Remember that attributes marked as domainKey or domainDescription will be shown in combo boxes as descriptors for the respective underlying DTO. An entity definition like:

entity ProductClass { 
     persistenceUnit "businessdata" 
     uuid String ^id 
     domainKey String productSearch 
     var String productSubcategory 
     var String productCategory 
     @PostLoad def void fillProductSearch() { 
          productSearch = productCategory + " - " + productSubcategory 
     } 
}

This will lead to combo box entries that are combined of category and subcategory.

I18N.properties (Reorganization of obsoleted values)

Question:

Each DSL has its own I18N.properties to translate the values. The property file includes values that are no longer used in the Modell-Description. (For example based on an addition correction of orthography)

The update of the properties seems to be one-way. Is there a function to reorganize the values (with the target to drop all obsoleted values)?

Answer:

No, there is no way to delete unused entries for security reasons. Translations to foreign languages are expensive. The modeler is responsible to delete obsoleted entries.

Display values from ENUMS in Table

Question:

We are using a perspective with the combination of table and dialog to maintain master data. The dialog contains combo-boxes to select values based on ENUMS. The selected value is displayed in the dialog, but is not displayed in the table. Is there a way to display the values of the selected ENUM in the table, with the objective to use the filter?

Answer:

This is not yet implemented but on schedule.

References to images

Question:

Using for example MENU.DSL Documentation:

package <package name>[{ 
expandedImage <expandedImage String>

Keyword expandedImage and collapsedImage is used to define the menu image when the menu expanded or collapsed. Where can we find the valid names of the Images to use in the String?

Answer:

The images can be selected by using hitting <CTRL>+<space> right behind the keyword. This will lead you to the image picker. Double-click on "Select icon...“ , then you can select the image from the image pool. The corresponding name will be added to the model. If you want to add own images to the pool follow How to add pictures.

Perspective with master/slave relationship

Question:

We created a perspective with a "master" table and 5 related "slave" tables. The target is to select one row in the master table and automatically filter the data rows in the slave tables related to the selected data. Where can we find information about the way to realize this goal?

Answer:

With "master" you probably mean an entity that has relative to the "slave" an one2many relationship. Views of their underlying tables will synchronize if they share a filter with the selection of another table. The filter must use the same entity as the entity of a table that selected a row. So every datamart of a "slave" must have a condition in a many2one join where the "one" side is the entity that should synchronize while selecting rows. In effect the selected row tries to change all filters to the same ID if the same entity is used. This applies to all open views in all open perspectives. In datamartDSL, using the keyword "filtered", the result in the application is a combo-box in the header of the table, which allows to select a value which is used as a filter of all tables of the perspective which have use the same condition; using the keyword “selected”, the result will be a list-box.

filtered (optional) => Combo-box

selected => List-box

Perspective use border to show boundary for each sash

Question:

Is it possible to show border between each sash-container used in a perspective? From our point of view the arrangement is not pretty clear to the user. It could be helpful to get a clearer view to show (optional) real visible border between sash-container and even between parts. for example:

• green border between parts of a sash-container
• blue border between sash-container

Is this already possible?

Answer:

For the moment there are no plans to colorize borders by means of grammar keywords. It is possible by changing the CSS for the currently selected theme.

Datainterchange Export (does not overwrite existing file)

Question:

We defined an interchange for a specific entity. The created TriggerView is called in a perspective, which is called in the menu. We also used an adjusted dialog with a toolbar with the export command. When the defined target filesystem is empty, the export file was created. A second try to export the data does not create a new file. Is there something to consider to allow an "overwrite" of existing data?

Answer:

Datainterchange tries not to overwrite already exported files and appends a running number to the end of the filename. When it is not work, you have to debug. The Action-buttons of the created Trigger-View are accidently colored as disabled but they are not. This will be changed in the future.

If you think they are very pale (not easy to read). It is also possible to define the layout of the buttons.

Logged in user as part of the data-record

Question:

We want to create an entity, where the logged in user, who insert a record is referenced in each data-record that be created. Is there a way (function or something else) to handle this request?

Answer:

This request is already a ticket.

bpmn2 file reference in blip-DSL

Question:

There is no hint about where to save the *.bmpn2 files. So we created a subfolder in net.osbee.app.XXX.model.blip, which is named of “bpm”. Using the new subfolder we created a new jBPM Process Diagram. As the description during the creation we remove "defaultPackage." as Prefix for Process-ID: The model is simple (Start-Event / User-Task / End-Event) When we try to reference the bpm2 model inside the blip-dsl, the name could not be resolved. Is there something to take care about?

Answer:

You must right click the new folder “bpm” and when the mouse is over "Build Path", select "use as source folder". After this is done you should press STRG+SHIFT+O in the Blip DSL to "organize imports".

How to add the missing icon images to a new created ENUM combo box

Question:

Defining an ENUM at the entity DSL model instance, a corresponding combo box is created, but the corresponding icon image for each ENUM component is missing.

Answer:

For the solution have a look at How to add pictures. We would like to enforce the usage of icons in OS.bee. So if you use EnumComboBox without images, there will be a "missing icon" icon appears in the combo-box, it was introduced with intent to remind the designer that there is a missing icon. There is still a problem, in the case, for example there are 10 Enum values per Enum type and 10 Enum types are used in an entity, 100 image names must be generated and deposited. Even if all use the same picture. This takes a lot of effort and costs time - just writing the file names per picture. Some of the designer wants to use EnumComboBox without images. Although great user experience comes from great effort, for designers who want to hold on to the slipshod way we will introduce a setting in OS.bee preferences to avoid displaying icons at all when at least one of the entries of a combo box is missing. For a pretty user experience we must decide between text and icon per combo box.

table DSL (as grid) create new data records

Question:

Is it possible to create new data records while using a grid? Existing data records can be changed for defined attributes (editable prop) using a double-click on the data row What must be changed to allow the creation of data rows?

Answer:

This is not yet possible, but on schedule.

DSL entity (Multiplicity of properties)

Question:

We defined an entity for customer data, with the goal that some attributes must be entered during creation of new data-records. To use only the property seems not to be enough to prevent a data-record to be saved, without filling non-nullable attributes. What have to be done to reach the goal?

Code-example:

var int [1]customer_no
var String [1] customer_name
var boolean portalrequired
var String country

Snippet of documentation

Answer:

This is a very interesting question. So I will explain some important facts about binding and validation (formerly known as Plausi). As OS.bee implements the Model-View-Controller pattern, UI fields, business logic and data layer are strictly separated. The link between them is realized by a "bean binding" mechanism. This mechanism propagates changes between the MVC elements in every desired direction. There is a layer between this mechanism which is called bean validation. For every direction of binding a validation can be implemented to avoid or allow a certain change. Even conversions between values from model to presentation and vice-versa are implemented in the binding mechanism. There are some pre-defined validation rules available in the Datatype DSL. As we follow the domain concept to define things as close to the base of the DSL hierarchy as possible, this is the place to go for validations.

For your request, you must define a new datatype as following:

datatype StringNotNull jvmType java.lang.String isNotNull[severity=error]

You can apply a validation rule to every "non-primitive" jvmType (jvm = Java Virtual Machine): Double, Integer..., but not for double, integer... Validation rules are cumulative. The severity of the user response on violation of the rule is definable in 3 flavors:

1. info
2. warn
3. error

Each of them stylable via CSS. The following validation rules are available right now:

• isNotNull
• isNull
• minMaxSize (applies to Strings)
• maxDecimal and minDecimal (applies to Double, Long and Integer - Float is not supported by OS.bee)
• regex (regular expression must be matched - for the advanced designer)
• isPast (applies to date)
• isFuture (applies to date)

► Examples:

datatype DoubleRange jvmType java.lang.Double maxDecimal (10.00) minDecimal (20.00)
datatype String5to8Chars jvmType java.lang.String minMaxSize(5,8)

As a last step you must use the newly created datatype in your entity to let the validation work. There is one additional validation accessible as keyword from the Entity DSL. If you want to enforce the uniqueness of an attribute value like "fullName" you can use the unique keyword in the entity.

► Example:

entity Employee extends BaseID {
	persistenceUnit "businessdata"
	domainKey unique String fullName

When you are about to save a newly created entry, during bean validation the database is accessed and it is verified, that the given attribute content is not already in the database. Else a validation error with severity error appears in the front-end.

UI-Design

Question:

Is it possible to design a Combo-box/List-box where I can sort the entries by myself? Like in eclipse > Configure Working Sets... Here I ‘m able to select Up / Down to sort the working sets.

In the moment I realize this in the entity with the field listPrio:

entity Title extends BaseUUID {
persistenceUnit "businessdata"     
domainKey String 
title var 
int listPrio 
}

Then I sort the entries by giving a value for listPrio. But this is not a good solution.

Answer:

Sorry, not for this time. Sounds useful. I will create a ticket for it.

DSL Dialog: Autosuggestion for DomainKey or DomainDescritpion

Question:

I develop an address management. In the Entity DSL, I have the fields:

domainKey String decription
var String firstname
var String lastname

If I create a user:

firstname: Hans
lastname: Maier

Is it possible to get for the field description automatically suggested the value: Hans-Maier? Like a kind of derived or Operations in Entitiy DSL, but only for suggestion.

Answer:

Yes. After the definition of all attributes, you have the possibility to define methods that can be called by JPA thru annotations.

 
domainKey String description
	...
	@PostLoad
	def void makeFullName() {
		description = firstName+"-"+lastName		
	}

Remember that decription is completely transient. You could also use @PrePersist or @PreUpdate.

DSL Table

Question:

I have a Table with 100 address data.

Is there a possibility of multi-selection?

► Example of selection of 5 addresses:

• I want to delete in one step 5 addresses.
• I want to send to these 5 addresses the same email.

Answer:

Not for the OSBP version. If you have the BPM option, then the token for BPM can be built using a selectable table. The resulting workload could send emails or deletes against the data base in the following system task.

datamart DSL (condition filtered) table does not refresh

Question:

In a perspective we use organigram / table (user) / dialog (user). The table based on a datamart using the semantic element conditions. Not all position in the organization have assigned user. When a position with assigned user is selected the data rows of the table are filtered. When a position is selected (where no user is assigned) the table does not refresh. What can we change in the model to refresh the table even when there is no corresponding data?

Answer:

DSL authorization (CRUD)

Question:

We tried to authorize the CRUD operations for some position in different ways. All CRUD operations for a given entity "Customer"

Position Accounting

Position ProjectIntern

Assumpiton:

• For each positon there i a user available
• Each position has an assigned rolte (organization)
• Both user uses the same perspecitve (table/dialog)
• The dialog uses a general toolbar with the necessary actions

Login with user assigned to Position Accounting, create a new datarow (new Customer) and save the data (o.k) Login with user assigned to Position ProjectIntern, select the new Customer in the table, activate delete Button (Row deleted not expected) Is there something to take care about we neglected?

Answer:

DSL Menu(UserFilter/SuperUser)

Question:

When a User marked as SuperUser logged in our Application and the Menu-Modell contains a definition for UserFilter. The Menu is no longer shown inside the application.

The last lines of the Menu-Model

The generated Menu in the application looks like this:

If the UserFilter line is included and the application restarted, after login, the application looks like this: (User,Position, and Menu are not visible)

The entity UserAccount and UserAccountFilter have been consider in authorization-DSL with Value ANY assigned to the role used by the user with attribute SuperUser.

Answer:

Printer Selection (Default Printer)

Question:

The Combo-box (Client-Toolbar) for the print-service shows all Printers from the client operating system. The default printer of the operating system is not the preselected for the application. It is possible to define a print-service for each user within the dialog UserAccount? Is it possible for an administrator to select Print-Service for foreign user without having all print-services on his local operating system? Or is it possible to preselect the default print-service insinde the client?

Answer:

DSL Entity Enum with own images

Question:

We tried to create own images for Enum-Values following the document How to add Pictures hosted using URL:

► Example:

 
enum TypeDocument {
             PDF, DOCX      }
entity Customer {
persistenceUnit "businessdata"
domainKey String customerKey
id int no
var boolean portalrequired
           var String country
           var TypeDocument documenttyp }

Own Fragment Bundle

Question:

1. There is no hint about image sizes, are there some restrictions?
2. There is no preferred way to transfer the created images into the folder (We use Copy and Paste, are there other ways?)

The application started from within Eclipse, Create new data-record using a dialog, the created images are not shown inside the Combo-Box. Can you help me about what went wrong or what is missing?

Answer:

How to synchronize views

Synchronizing tables with dialogs is quite usual for OS.bee. If they share a common entity and they are placed on the same perspective, this is done automatically.

You can now even synchronize tables with reports or tables with tables. They must have an identifier column in common. If so, they are synchronized without the need of a common datamart condition. The receiving view must have the keyword "selectById" on it. Every table emits a selection events of all id columns in the datamart. Not only the id value of the root entity, but also relations emit its id value when displayed in a table and selected.

If you have a datamart of a table with entities related like A->B->C, the selection event emits the values of the selected row of A.id, B.id and C.id. If there is another view on the perspective which uses A, B, or C as root entity, it will automatically synchronized.

There are 2 prerequisites that must match that the receiving view will synchronize automatically:

• the relation of the source view that should work as synchronizing element for the target view must appear as opposite relation in the datamart of the target view.
• the target view's datamart must have at least one normal attribute to show in the associated view.

How to get new features from your toolbar

As you probably know, ActionDSL creates commands, tool items and toolbars. There are some new features that you could use to enhance the usability of your dialog designs. Besides the classic buttons to save, delete, restore or create new entries, there are two new possibilities:

• save and new
• save as new

save and new is quite simple: after saving the dialog will enter the new-entry-mode again and re-uses the previously selected sub-type of the underlying DTO if there was one. The normal save will stay in editing-mode after save was processed.

save as new allows to make copies of the currently selected entry. If there are no uniqueness validations on the dialog, the copy is exactly the same as the previous entry, except for the internally used ID field. If there is a need to create a lot of new entries which are similar to an already existing entry, this button will help reducing time to enter new entries.

How are these new buttons created?

1. create 2 new commands in ActionDSL (you could use your own keybinding shortcut)

    
   	command saveAndNew describedBy "save and new" keyBinding "CTRL ALT A" dialogAction SaveAndNew
   	command saveAsNew describedBy "save as" keyBinding "CTRL ALT F" dialogAction SaveAsNew
   

2. add the new commands to your toolbar which is used in your dialogs

    
   	toolbar Dialog describedBy "Toolbar for dialogs" items {
                   ...
   		item saveAndNew command saveAndNew icon "dssaveandnew"
   		item saveAsNew command saveAsNew icon "dssaveasnew"
                   ...
   	}
   

Add user information to your CRUD operations

Sometimes it is desired to have some information persisted concerning the user and the date when an entry was created or modified. This is how this is to be implemented: First you must add the necessary attributes to the entities where this information is needed. If you use a mapped superclass for all entities, it makes it very simple to add it to all entities at once. These attributes must be annotated with the appropriate tag so that the generators know what you want (supply metadata).

Here is an example if using mapped superclasses:

 
	mappedSuperclass BaseUUID {
		uuid String id
		version int version
		
		@CreateBy
		var String createUser
		@CreateAt
		var Timestamp createAt
		@UpdateBy
		var String updateUser
		@UpdateAt
		var Timestamp updateAt
	}

The same thing also works for dedicated entities as well. If the EntityDSL inferrer discovers one of the annoations @CreateBy, @CreateAt, @UpdateBy or @UpdateAt it checks the following attribute definition and if the datatype matches the annotation the JPA mechanism will enter the requested information into the new or modified record. So be careful with the datatype, the ...By annotation expect a String to follow, the ...At annotation a Date type.

• How to make it visible to the runtime-user?

You must supply a toolbar command in ActionDSL to enable the user to show the information:

 
command databaseInfo describedBy "database info" keyBinding "CTRL ALT I" userinterfaceAction Info

Then you must extend your dialog toolbar with the new command:

 
toolbar Dialog describedBy "Toolbar for dialogs" items {
        ...
	item databaseInfo command databaseInfo icon "dbinfo"
}

You will end up with this toolbar button:

If the user clicks this button or uses its shortcut, a popup window appears showing the requested info. As the user selects different entries and leaves the popup open, its content will refresh according to the underlying information.

Designing dialogs using multiple columns

Generally there are two ways to define dialogs in OS.bee:

1. using UI model manually
2. using autobinding automatically

The advantage of using UI model is that you can create sophisticated nested layouts and use more than one DTO to bind from even if they don't have a relationship. The disadvantage is that you have to layout and bind manually. If DTO changes, you must also change the depending UI models.

The advantage of using autobinding is that you have nearly nothing to do if your dialog exactly follows the DTO description. A mechanism collects all available metadata from the underlying entities/DTO and tries to render a suitable dialog. The disadvantage is that you can't change layout nor the look.

Except for a new feature in DialogDSL. You can tell the dialog to render a multi-column layout. Just enter the keyword "numColumns" and a number in the dialog grammar.

dialog Products describedBy "Products" autobinding MproductDto toolbar Dialog numColumns 2

This will result in a 2-column layout like this:

This is how it looks with 3 columns:

Grouping attributes on dialogs

Sometimes there is the need to cluster fields on dialog to logical groups. Thus enforcing readability and better understanding of complex data entry forms (dialogs).

To enable the designer to do so, there is a new keyword "group" followed by an id in the grammar of EntityDSL. The layouting strategy logic of OS.bee finds common ids and collects the attributes together no matter in which order they appear in the entity. The group id cannot have blanks or special characters. The id is automatically added to the i18n properties of EntityDSL in order to be translatable.

Grouped and non-grouped attributes can appear mixed on a dialog. An example for the definition is here:

	entity Mproduct_class extends BaseID {
		persistenceUnit "businessdata"
		domainKey String product_subcategory group category
		var String product_category group category
		var String product_department group department
		var String product_family
		ref Mproduct[ * ]products opposite product_class asGrid
	}

The dialog is defined like this:

dialog Product_class describedBy "Product Class" autobinding Mproduct_classDto toolbar Dialog numColumns 1

The resulting dialog at runtime look like this:

As you can see the field "product family" is not grouped and the one-to-many relationship to products is rendered on a separated tabsheet because the keyword "asGrid" is used for the reference definition.

Here a more complex example for products with a 2-column layout:

entity Mproduct extends BaseID {
	persistenceUnit "businessdata"
	domainDescription String product_name		group category
	var String brand_name 			group category
	var String sku 				group domain
	domainKey String fullName 			group domain
	var double srp 				group sales
	var boolean recyclable_package 			group customerinfo
	var boolean low_fat 				group customerinfo
	var MassGRAMMetricCustomDecimal net_weight	group logistics
	var int units_per_case 				group logistics
	var int cases_per_pallet 			group logistics
	var MassGRAMMetricCustomDecimal gross_weight 	group logistics 
	var LengthCMMetricCustomDecimal shelf_width 	group spacing
	var LengthCMMetricCustomDecimal shelf_height 	group spacing
	var LengthMetricCustomDecimal shelf_depth 		group spacing
	var ProductClassification classification		group category
	var PLUNumber plu 				group sales
	var String pluLabel 				group sales
	ref Mproduct_class product_class opposite products 	 group category
	ref Minventory_fact[ * ]inventories opposite product
	ref Msales_fact[ * ]sales opposite product 
	ref CashPosition[ * ]cashPositions opposite product asGrid
	@PostLoad
	def void makeFullName() {
		fullName = sku+"\t"+product_name
	}
	
	index sku_index {
		sku
	}
	index plu_index {
		plu 
	}
}

How units of measurements are handled

Often it comes to the situation that a certain value is bound to a unit of measurement. Lengths or masses are common examples. OS.bee supports units of measurement by using a framework called UOMo.

This dialog shows the usage of UOMo in the "Logistics" and "Spacing" group:

If you enter a big value into "Net Weight" for example, the logic will convert it to another unit in the same unit-family:

So there is some business-logic for uom implemented under the hood. When you look at the entity of this attribute, you'll find:

var MassGRAMMetricCustomDecimal net_weight	group logistics

and in DatatypeDSL it look like this:

datatype MassGRAMMetricCustomDecimal jvmType java.lang.Double asPrimitive
	properties (
		key="functionConverter" value="net.osbee.sample.foodmart.functionlibraries.UomoGRAMMetricConverter" 
	)

So what you can see is that the basic type is Double and a converter handles the uom stuff. Let's look at the FunctionLibraryDSL for this definition:

converter UomoGRAMMetricConverter {
	model-datatype Double presentation-datatype BaseAmount
	to-model {
		var localUnitFormat = LocalUnitFormatImpl.getInstance( presentationLocale );
		var baseUnit = localUnitFormat.format( MetricMassUnit.G ) var suffix =( presentationParams.get( 1 ) as String ) if( suffix === null ) {
			suffix = baseUnit
		}
		if( localUnitFormat.format( MetricMassUnit.KG ).equals( suffix ) ) {
			var amount = MetricMassUnit.amount( presentationValue, MetricMassUnit.KG ) return amount.to( MetricMassUnit.G ).value.doubleValue
		}
		else if( localUnitFormat.format( MetricMassUnit.MG ).equals( suffix ) ) {
			var amount = MetricMassUnit.amount( presentationValue, MetricMassUnit.MG ) return amount.to( MetricMassUnit.G ).value.doubleValue
		}
		else {
			return presentationValue
		}
	}
	to-presentation {
		var amount = MetricMassUnit.amount( modelValue, MetricMassUnit.G ) if( modelValue > 1000d ) {
			amount = amount.to( MetricMassUnit.KG )
		}
		else if( modelValue < 1d ) {
			amount = amount.to( MetricMassUnit.MG )
		}
		return amount as BaseAmount
	}
}

You discover for this function a logic separated in two parts:

• to-model
• to-presentation

As the function must provide a logic to convert database values to the UI (presentation), and after the user changed a value, back to the database (model), it has two parts. The 2. part is called the inverse function. Each part tries to find the most suitable unit for the given value. The base-unit is defined as metric gramm and all other values stay in the same family. As a result the value is stored in base-units.

While you play around with units of measurement you'll find out that you could easily build converters between families but also to convert from imperial unit systems to metric (SI=Système international d'unités ) and vice versa.

How sliders can improve the user experience with your dialogs

Sliders are well known to adjust analogue values in the world of audio.

If you want to use a similar technology to let your user adjust values in an analogue manner, you can use sliders. Just define a new datatype based on a numeric primitive type and supply it with the minimum and maximum values for the adjustable range.

datatype Slider_1000_2000 jvmType int
	properties(
			key="type" value="slider", 
			key="min" value="1000", 
			key="max" value="2000"
	)

Use the new datatype in an entity:

var Slider_1000_2000 slideDelay

The resulting dialog looks like this:

It looks kindof more convenient instead of entering a number between 1000 and 2000.

New ways to supply icons for enum literals

Icons are now automatically generated when the entity model is generated. In every location of entity models a folder "enums" will be created and one sub-folder for each type of enumeration. Every literal of the enum will create a png-file with size 1x1 white pixel. This makes it easy to supply a custom icon for every enum literal located near the definition. You just copy a 16x16 pxel sized png file over the generated one. There is no need to suppress icons if no icons are needed as they are invisible when generated 1x1 pixel sized.

After generation the folders look like:

After you have overridden the icons, the combo box looks like this:

IMPORTANT: you must modify your build.properties like described here.

Core Dev

New event for statemachines

Statemachines working in combination with UI model can exploit a new feature of the component SuggestText. The SuggestText-component will send an event "onSelection" as soon as the user picked an entry of the popup list. FiledName must be a field definition of the controls section of the statemachine model. The first letter of the name is capitalized to meet the camel Case naming convention. E.g. the field "foo" which is bound to a SuggestText component will emit the event "onFooSelection". Using this event in a statemachine can trigger an action after a user selection of a SuggestText-popup-entry for further processing.

Duplicate translations

Each DSL and some other bundles come with a set of dedicated I18N property files, containing translatable items and the preset amount of target language translations. Each language has its own key-value pairs. The keys are derived from element-ids or other designated translatable strings inside a DSL grammar. All bundles of a product's target platform are scanned for those property files at startup of runtime and translations are cached inside the DSLMetadataService for fast access. By the way, DSLMetadataService also holds the models of all DSL for reference at runtime. Occasionally it happens that the same key is used in different models but with or without valid translation for each target language. There is no need to translate the same key over and over again. Since today there is a method to detect the best translation for each language using the Levenshtein Distance Algorithm. The idea is that the more distant a value is from its key, the better is the translation. On startup, the translation cache is filled with those translations that are most distant from the key. In other words: correct translations that compete against defaults or sloppy translations will make it to the cache, thus increasing the quality of the displayed translation. Additionally there is a new console output indicating duplicates in bundles as error information and surviving translations per language and key as debug information.

Edit WelcomeScreen

As for today it is possible to edit the WelcomeScreen and save the new content permanently in the Preferences of your product. This is how it works: Start the application and stay at the Welcome Screen. With the right-mouse button while holding down the STRG+ALT keys, click 5 times at the top-left area of the Welcome Screen. The sensitive area is 50px in square. A rich text editor will appear instead of the static screen. Use the tools of the editor and if you are ready, do the 5 times click stuff again to save it and switch back to static mode. If you want to display images from the in-build themes, you must enter the following path preceding the filename: VAADIN/themes//image/logo_osbee.png for example. It is the currently selected startup theme e.g. osbp.

Here is a list of in-build images you could try (The images are taken from pixabay.com):

2M1AXEU9Q2.jpg app-loading.jpg binary-797263_1920.jpg binary-797274_1920.jpg bkgnd1.jpg cpu-564789_1920.jpg grid-684983_1920.jpg grid-871475_1920.jpg key.png logo_osbee.png padlock.png personal-95715_1920.jpg rain-455120_640.jpg statistics-706383_1920.jpg Top_view.jpg U68NITW3EI.jpg U68NITW3EI_s.jpg

If you need to restore the original WelcomeScreen just delete the tag welcomeScreen from your preferences file.

Search

When you think about searching and retrieving data, two use cases will come into your mind:

• find an entry of an entity to edit its properties
• find an entity to establish a reference.

For both cases there is a new feature dealing with filters and search views. If you want to pick an entry and don't know exactly its name, you filter all of your entries by means of filtering. There are two types of filters implemented:

• Compare filters (using keyword “filter”)
• Range filters (using keyword “range”)

Compare filters can match an attribute by a set of comparison operators:

• equal
• unequal
• greater
• greater equal
• less
• less equal
• like (you could use the following wildcards:

  % matches any number of arbitrary letters

  $ matches exactly one arbitrary letter).

Range filters expose two fields (from...until) where the inclusive borders of the range can be applied. You can supply filter metadata at the entity model by using the keywords "filter" and "range" like this:

 
domainKey String fullName
var String firstName
var filter String lastName
var range BirthDate birthDate
var range double salary

this means that "lastName" will have a compare filter, where "birthDate" and "salary" will have a range filter. In addition to this filters on direct attributes it is also possible to walk along the reference tree and add so called nested attributes for filtering. How deep the tree is iterated can be defined in the metadata by using keyword “filterDepth” like this:

 
ref filterDepth 01 Position position opposite employees

And in the Position entity:

 
var filter String payType

The keyword “filterDepth” limits the depth of iteration, in the example to 1 iteration. The resulting search view is automatically generated and looks like this:

The filtering can be accessed by the filter button right to the combo-box dropdown-button or you can place a search-view inside a perspective by using this syntax:

 
part EmployeeSearch spaceVolume "60" view search in MemployeeDto depth 3 filterColumns 1

In the perspective you can override the depth metadata from entity and tell the layouter either to arrange all filtering attributes in 1 column or 2 with the keyword “filterColumns”.

DataInterchange is externally configurable by admins

The latest version of DataInterchange implements a new feature. Whenever the model is saved, not only the java classes and the smooks configuration is written, but also a file to modify the import and export paths is written out. The file is interpreted using the Properties xml import and export method and looks like this:

 
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE properties SYSTEM "http://java.sun.com/dtd/properties.dtd">
<properties>
<comment>dataInterchange file URLs</comment>
<entry key="EmployeesDepartment-import">C:/myimports/employeesdepartment.xml</entry>
<entry key="EmployeesDepartment-export">C:/myexports/employeesdepartment.xml</entry>
</properties>

By default, this file is named like the title in the dataInterchange package and extended by "Config" and has the extension "xml".

 
package net.osbee.sample.foodmart.datainterchanges title "DataInterchange" {

leads to the filename: DataInterchangeConfig.xml

and is stored platform independently in the current user's home directory under the subdirectory ".osbee".

An administrator must receive this configuration file with the application, modify it and place it somewhere on the application server. The path to this configuration file must be given in the product's preferences (org.eclipse.osbp.production.prefs): datainterchange/datainterchangeConfiguration=c\:\\DataInterchangeConfig.xml The path value obviously depends on your operating system.

In the Eclipse IDE the setting looks like this:

Statemachine (FSM) handles external displays

The latest development for the Statemachine DSL (Finite State-Machine) covers the synchronization of external (slave) browsers to a main (master) browser connected to an OS.bee server. The requirement was mainly inspired by the need of a customer display for the OS.bee POS application OS.pos. In this context it is required parts of the main screen's data which is shared on the slave browser working as a display.

Multiple displays can be connected to a master just by using a pattern on the address line of the slave-browser:

  http://{server host-name}/osbpdisplay/#{host-name of the master}-{DisplayName as defined in the ui model}

► e.g.: http://dv999.compex.de:8081/osbpdisplay/#dv888.compex.de-CustomerDisplay

The FSM supports some new keywords to do so:

•  display <DisplayName> using <DTOName>
  

•  dto <DTOAlias>  type <DTOName> attach <DisplayName>
  

•  displayText text "some text" @<DisplayName> to <DTOAttribute>
  

The references of a DTO that is attached to a display are always synchronized across all connected displays. Single fields must be synchronized by displayText.

► e.g.:

dto cashslip type CashSlipDto attach CustomerDisplay
display CustomerDisplay using CustomerDisplayDto
displayText text "locked" @CustomerDisplay to message

► Attention: the formerly used keyword displayText was related to lineDisplays and is now reused for displays. That means for an update to this version, all displayText keywords must be changed to lineDisplayText.

The referenced DTO must be the rootType of the Display definition in the ui model:

display Customer {
	rootType CustomerDisplayDto
	datasource main:CustomerDisplayDto
	verticalLayout left {
		textfield(i18n noCaption readonly) message
		table(i18n noCaption) slip {
			type CashPositionDto
			columns {
				column quantity
				column product.sku
				column product.product_name
				column price
				column amount
			}
			sort {
				column now asc
			}
		}
		align fill-left
		bind [this.message].value <--> main.message
		bind [this.slip].collection <--> main.slip.positions
	}
}

Database Support

Which database systems are supported by the OS.BEE Factory Software? The OS.BEE Software Factory currently supports 4 different database management systems:

• MySQL
• Oracle
• H2 Database Engine
• Apache Derby

The corresponding settings have to be inserted into the product configuration of your application. Within your Eclipse workspace, open the preferences by clicking to the menu “Window -> Preferences -> OSBP Application Configuration” and choosing first the right product configuration file – the configuration file pointing to your application project (e.g. org.example.yourprojectname.application/.metadata/.plugins/org.eclipse.core.runtime/.settings/org.eclipse.osbp.production.prefs). Afterwards you can go on to the “Data Source” subsection and enter the information needed for the database you would like to use.

For instance, if you are using an Oracle database as persistence layer for your application, you will set up all the information of the database connection into a JNDI Data Source, in which you will choose the database, its fully classified driver class name and the remaining information such as server name, port and account credentials as shown below.

JNDI Data Source – Oracle

Similarly you may create further data source instances if needed by duplicating or editing existing ones like shown below for MySQL and H2 In-Memory.

JNDI Data Source – MySQL

JNDI Data Source – H2 In-Memory

After setting the data sources you would like to use inside your application, all you need to do at last is to specify in each persistence unit instances which data source to use, as shown below.

The persistence units are used on the entity level to identify where certain data are located, in this case in which database. This also gives you the flexibility of storing and retrieving data from multiple data sources. For instance, user credentials (persistence unit: authentication) and other business related data (persistence unit: businessdata) would be stored in an Oracle database whereas business process management (persistence unit: BPM) related data would be stored in a MySQL database due to some organizational decisions… Further information on how data are persisted, can be found in the Entity DSL documentation page.

You may also have a look on the OS.bee Software Factory documentation pages.

Combo box handles now more complex objects

Question:

How to define a combo box that holds an object composed of an id and a label and display only the object label on screen but persist the object id?

Answer:

Until now the type of the object that holds the combo box was also the type for its selection. So it was only possible to persist the type that holds the combo box. The enhancement done on the combo box is that an additional model selection type ("modelSelectionType") can be defined. So the combo box definition can have two different types, one for the objects that the combo box holds in its collection ("type") and another for the information that has to be persisted for the selected object ("modelSelectionType") within the combo box. Due to this change using an object A composed with the attributes id and label from type String a combo box can hold the object A as the type for the container but the type String for the selected item as for example its id. The model to presentation conversion from the container type to the selection type (object A to String) has to be done by an individual converter (as these) implementing YConverter. Example using as type for the collection VaaclipseUiTheme (JavaDoc) and displaying on screen the VaaclipseUiTheme label but persisting its id:

YComboBox yCombo = (YComboBox) ExtensionModelFactory.eINSTANCE.createYComboBox();
yCombo.setUseBeanService(false);
yCombo.setCaptionProperty("label");
yCombo.setType(VaaclipseUiTheme.class);
yCombo.setTypeQualifiedName(VaaclipseUiTheme.class.getCanonicalName());
yCombo.setModelSelectionType(String.class);
yCombo.setModelSelectionTypeQualifiedName(String.class.getCanonicalName());
yCombo.getCollection().addAll(getThemes());
YConverter conv = YConverterFactory.eINSTANCE.createYVaaclipseUiThemeToStringConverter();
yCombo.setConverter(conv);

For more information how to use our combo box have a look on: YComboBox (JavaDoc)

Enriching csv files to highlight complex information

Although it is possible to read and import data from csv files with the help of csv reader tools, the reading process doesn’t consider possible existing relations between the data contained in those files. What is missing here is the possibility to enrich those file with the metadata information needed to highlight the presence of relations between the flat data contained in a bundle of different csv files; thus, giving users the means to set up information over complex structures. With the CSV2App module of the OS.bee Software Factory, you are now able to set additional metadata information into a csv file, by enriching its column definitions. This allows users to define a set of configurations, which will be used to create more complex entity structures, and so forth more complex applications (entities, tables, actions, menus, dialogs…). You can get more information here. You may also have a look on the OS.bee Software Factory documentation pages.

Max File Size BlobMapping

Question:

What is the biggest file size allowed to be imported/uploaded into an OS.bee (created) Software?

Answer:

Some information about the OS.bee BlobMapping data type can be found here. Some information about the database systems currently supported by the OS.bee Software Factory can be found here. You may also have a look on the OS.bee Software Factory documentation pages.

How to show JavaScript compile errors building the Widgetset

Due to a bug in the vaadin-maven-plugin a system property needs to be specified invoking the guid. For normal the -strict option in the pom should do it. But <strict>true</strict> leads to an error, that -failOnError is not a supported option.

Just call the widgetset build by:

mvn clean verify - Dgwt.compiler.strict=true

Then the build will break if errors during the widget set compilation occur. And the console will show the error problems. There is also a similar option -struct. This will break the build even if warnings occur.

Apps

Launch my1app - error

Question:

Following is the error when launching my1app :

java.lang.RuntimeException: Error initializing storage. at org.eclipse.osgi.internal.framework.EquinoxContainer.(EquinoxContainer.java:77) at org.eclipse.osgi.launch.Equinox.(Equinox.java:31) at org.eclipse.core.runtime.adaptor.EclipseStarter.startup(EclipseStarter.java:295) at org.eclipse.core.runtime.adaptor.EclipseStarter.run(EclipseStarter.java:231) at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method) at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:62) at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:43) at java.lang.reflect.Method.invoke(Method.java:498) at org.eclipse.equinox.launcher.Main.invokeFramework(Main.java:648) at org.eclipse.equinox.launcher.Main.basicRun(Main.java:603) at org.eclipse.equinox.launcher.Main.run(Main.java:1465) at org.eclipse.equinox.launcher.Main.main(Main.java:1438) Caused by: java.io.EOFException at java.io.DataInputStream.readInt(DataInputStream.java:392) at org.eclipse.osgi.container.ModuleDatabase$Persistence.readWire(ModuleDatabase.java:1168) at org.eclipse.osgi.container.ModuleDatabase$Persistence.load(ModuleDatabase.java:1028) at org.eclipse.osgi.container.ModuleDatabase.load(ModuleDatabase.java:879) at org.eclipse.osgi.storage.Storage.(Storage.java:145) at org.eclipse.osgi.storage.Storage.createStorage(Storage.java:85) at org.eclipse.osgi.internal.framework.EquinoxContainer.(EquinoxContainer.java:75) ... 11 more An error has occurred. See the log file null.

Answer:

This is kind of OSGi initialization error. Just stop all applications running, restart Eclipse and try again.

Launch my1app - error

Question:

Following is the error when launching my1app :

org.hibernate.tool.hbm2ddl.SchemaExport	- HHH000389:unsuccessful : alter table…

Answer:

Just in case you see this error message in the console during the start of your application it might be caused by a missing setting in the Eclipse IDE preferences. Please check the DS annotations setting as mentioned in the installation documentation. After you activate the generation of DS annotations, you have to rebuild the project. Then it starts properly.

Launching an app on OSX results in an endless wait after login

Question:

Launching an app on OSX results in an endless wait after login.

Answer:

If you experience an application hang after the login in an application launch from the Eclipse IDE on OSX, it might have the reason in the automatically created launch configuration. The checkbox "use -XstartOnFirstThread ..." should not be marked. Remove the mark, relaunch the application and it will work.

Update build.properties to make use of new feature

The OS.bee Softwarefactory now creates default icon files in a folder named "enums" in the bundle containing entity model files. It is neccessary to add this folder to the build.properties file of the bundle, otherwise the icons are not available in the final application. A sample build.properties file looks like:

source.. = src/,\
          src-gen/
bin.includes = META-INF/,\
               .,\
               .settings/,\
               OSGI-INF/,\
               i18n/,\
               enums/

How do i get the OS.POS-App started

Question:

There are three steps in the description download = ok extract = ok configure = ???

Answer:

Concerning the configuration of the connected peripheral units, there is a short answer: all peripheral units that can be connected have to follow the JavaPOS specification. There is a configuration file in xml format that has to be edited by programs of the peripheral hardware vendor. E.g. if you have Epson hardware, you must install the EPSON_JavaPOS_ADK_1143. After installing the appropriate drivers and programs , you can start "SetupPOS" and configure a POSPrinter, LineDisplay and CashDrawer, test their health with "CheckHealth". The path of the newly created configuration xml must be entered in the preferences file, then you can start OS.bee. There is a lot of configuration stuff in the preferences file which will be published step by step. Best way to edit is inside an Eclipse IDE under "OSBP Application Configuration".

Copyright Notice

All rights are reserved by Compex Systemhaus GmbH. In particular, duplications, translations, microfilming, saving and processing in electronic systems are protected by copyright. Use of this manual is only authorized with the permission of Compex Systemhaus GmbH. Infringements of the law shall be punished in accordance with civil and penal laws. We have taken utmost care in putting together texts and images. Nevertheless, the possibility of errors cannot be completely ruled out. The Figures and information in this manual are only given as approximations unless expressly indicated as binding. Amendments to the manual due to amendments to the standard software remain reserved. Please note that the latest amendments to the manual can be accessed through our helpdesk at any time. The contractually agreed regulations of the licensing and maintenance of the standard software shall apply with regard to liability for any errors in the documentation. Guarantees, particularly guarantees of quality or durability can only be assumed for the manual insofar as its quality or durability are expressly stipulated as guaranteed. If you would like to make a suggestion, the Compex Team would be very pleased to hear from you.

(c) 2016-2024 Compex Systemhaus GmbH