View source for OS.bee Tutorial

=OS.bee Tutorial=
==Introduction==

This tutorial will introduce the architecture, technology and functionality of OS.bee using basic OS.bee application '''My1App'''. 

'''My1App''' is a personal administration application consisting of a collection of models based on OS.bee Domain Specific Languages. It is generated by Eclipse wizards; the wizards build the Eclipse workspace, provide the basic structure and a number of consistent objects of models.

We use the "2BEE concept": 
# describe the requirements from the point of a fictive user with using story map
# technically implement the requirements of user

You can step by step expand the rudimentary person administration (which has only basic configuration) with the user stories described in the story map, and then generate an employee administration based on your new person administration.


Please notice:
* The task solutions can often be solved either by DSL code or graphic modeling. We will only present the solution with DSL code in this tutorial. You can use any one of them as you will.
* Each tutorial user stories are independent from each other; you don’t need to totally complete the tutorial in once.



==Purpose==

The task for the user of this tutorial is first the administration of personal data and then the main task is the administration of employee data.



==Requirement==

'''My1App''' is a personal administration application consisting of a collection of models based on OS.bee Domain Specific Languages. It is generated by Eclipse wizards; the wizards build the Eclipse workspace, provide the basic structure and a number of consistent objects of models. 
So before executing the tutorial steps in this tutorial using '''My1App''', the appropriate wizards must be installed. You can find more information about installation in [[My first app|doc of '''My1App''']].

My1App has the following basic objects:
* The ''superclass'' '''BaseID''', which has only one attribute identifier ('''id''') as '''UUID''' (See [[Entity_DSL#uuid|'''UUID''']]). It is the technical key as a basis of identification and it is an obligation for all entities.
* The ''entity'' '''Person''' , which inherits the identifier attribute ('''id''') from the ''superclass'' '''BaseID''' and has additional personal attributes.

The following vertically divided person-view represent the ''entity'' '''Person''' in '''My1App''', on the left side is the Person-Table  and on the right side is the Person-Dialog:
[[File:Tutorial_person_view.png]]

==Use cases==
The personal administration should be extended by the following use cases:
* change address 
* search person with full-name 
* establish current age of person
* add profile picture 
* add gender 
* add marital status

The expected employee administration is described by the following use cases: 
* hire employee 
* fire employee
* increase salary of employee 
* assign employee 
* transfer employee 
* evaluate employee


==Story map==
[[File:Tutorial_story_map_1.png|800px]]<br>
[[File:Tutorial_story_map_2.png|700px]]<br><br>

==User stories==
===Administration of personal data===
====Change the address====

'''Target''':

Introducing the EntityDSL instance by extending an existing entity with new attributes.


'''Requirement''':

As an administrator, I want to change a person's address.


'''User Task & User Story''':

[[File:Tutorial_user_story_change_address.png]]


'''Process''':

First of all, we need to set Street('''Person.street'''), City('''Person.city'''), Postal Code('''Person.postal_code''') and Country('''Person.country''') of a person. 

Following are new attributes for the entity person('''Person'''):
*street('''street''')
*city('''city''')
*postal code('''postal_code''')
*country('''country''')

These new attributes should be created as the extension of the entity person('''Person''').

After that, mocking data should be extended regarding to the new attributes, in order to already have data to use after restarting the application.
Or we can change the address by hand using the Person Table and Person Dialog UI.


'''Detail implementation''':

* Edit the EntityDSL model. (my1app.entity) (See [http://download.osbee.org/documentation/index.php/Entity_DSL Entity DSL] ).
**Add the attributes street ('''street'''), city ('''city'''), postal code ('''postal_code''') and country ('''country''') as variables of the entity person ('''person''').

[[File:Tutorial_code_change_address.png]]

new graphic view of entity Person:

[[File:Tutorial_code_graphic_entity_Person_change_address.png]]

* mock data:

[[File:Tutorial_code_change_address_mock.png]]


* After the creation of new attributes, we can change the address by calling up the person perspective via the menu entry of the person administration:

# Call up the Person Administration menu.
#* open the employee perspective:
#** on the left side is the table of all persons.
#** on the right side is the persons dialog.
#:[[File:Tutorial_person_view.png]]
# Edit a person.
#* Select an existing and already created person from the person table on the left side of the perspective.
#** Change the corresponding address attributes street('''street'''), city('''city'''), postal code('''postal_code''') and country('''country''') in the person dialog on the right side of the perspective.
# Save the changed personal data.

====Search person with full-name====

'''Target''':

Introducing a text search field and a function within the EntityDSL instance.


'''Requirement''':

As a user of the OS.bee application, I want to find a person through a name-search.


'''User Task & User Story''':

[[File:Tutorial_user_story_fill_full_name.png]]

[[File:Tutorial_user_story_search_with_full_name.png]]


'''Process''':

The full-text name search for a person requires a new attribute which show the full name ('''Person.full_name''') of a person. This full name should be filled by a function from the attributes ''first name'' ('''person.first_name''') and ''last name'' ('''person.last_name''') during the creation or modification.
* Creation of the new attribute full name ('''full_name''') as search text field.
* Creation of the function ('''full_name_function''') as extension of the entity person ('''person''').

'''Detail implementation''':

* Creating the new attribute full name ('''full_name''') as an extension of the entity person ('''person''').
** Edit the EntityDSL model ('''My1app.entity''').
*** Add attribute full name ('''full_name''') as variable of entity person ('''person''')
*** Define the full name field as search text field using keyword '''domainKey'''.

[[File:Tutorial_code_search_with_full_name.png]]

new graphic view of entity Person:

[[File:Tutorial_code_graphic_entity_Person_search_with_full_name.png]]

* mock data:
** To make the using of this tutorial easier, the corresponding full name data in the person-data-object are already exist at the beginning of My1App. You only need to add the full name attribute in the person mock entity.

[[File:Tutorial_code_search_with_full_name_mock.png]]

* Creating the new function ('''full_name_function''') as an extension of the entity person ('''person'''), which fill the full name ('''full_name''') from the first name ('''first_name''') and last name ('''last_name'''). 
** Edit the EntityDSL model ('''My1app.entity'''). 
*** Add the function ('''full_name_function''') as a process of the entity person ('''person''').
*** Fill the function with the annotations ''@javax.persistence.PrePersist'' and ''@javax.persistence.PreUpdate'' so that the content of the full name ('''full_name''') will be filled when the first name ('''first_name''') and last name ('''last_name''') attributes are created or changed.

[[File:Tutorial_code_search_with_full_name_function.png]]

* After the creation of new attributes and functions, we can test the functionalities by calling up the person perspective via the menu entry of the person administration.
# The full name should be filled from the first name and surname of a person .
#* Call up the Person Administration menu.
#** Open the employee perspective:
#*** On the left side is the table of all persons.
#*** On the right side is the persons dialog.
#* Edit a person.
#** Select an existing and already created person from the person table on the left side of the perspective.
#*** Change the corresponding name attributes first name ('''first_name''') and last name ('''last_name''').
#* Save the changed personal data.
#** In the full name ('''full_name''') field, the changed name appears.
# The full-text-name search of a person by calling up the person perspective via the menu entry of the person administration.
#* Call up the Person Administration menu.
#** Open the employee perspective:
#*** On the left side is the table of all persons.
#*** On the right side is the persons dialog.
#* Find a person.
#** Enter the search term (name part) in the search field with the full name ('''full_name''') in the persons dialog.
#** Select one from the suggested names.

====Establish current age====
====Add profile photo====
====Add gender====
====Add marital status====

===Administration of employee data===
====Create new entity of employee====
====Hire employee====
====Fire employee====
====Increase salary of employee ====

====Assign employee====
====Transfer employee====
====Evaluate employee====

= Copyright Notice =
{{Copyright Notice}}