[ofbiz-framework] branch trunk updated: Documented: HR Doc drive by process (OFBIZ-11026)

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
1 message Options
Reply | Threaded
Open this post in threaded view
|

[ofbiz-framework] branch trunk updated: Documented: HR Doc drive by process (OFBIZ-11026)

holivier
This is an automated email from the ASF dual-hosted git repository.

holivier pushed a commit to branch trunk
in repository https://gitbox.apache.org/repos/asf/ofbiz-framework.git


The following commit(s) were added to refs/heads/trunk by this push:
     new 5e6f537  Documented: HR Doc drive by process (OFBIZ-11026)
5e6f537 is described below

commit 5e6f5377087457b434a28c0b78643ab3ad1f9eac
Author: holivier <[hidden email]>
AuthorDate: Mon Sep 14 17:04:59 2020 +0200

    Documented: HR Doc drive by process (OFBIZ-11026)
   
    - Re-organize sub-chapter to have a process vision of HR component
    - Add hr-data-model sub-chapter
    - Add hr-appendix which list some bug or WIP development
---
 .../src/docs/asciidoc/_include/hr-appendix.adoc    |  77 +++++++++++++
 .../src/docs/asciidoc/_include/hr-data-model.adoc  | 123 +++++++++++++++++++++
 .../asciidoc/_include/hr-employee-positions.adoc   |  31 ++++--
 .../src/docs/asciidoc/_include/hr-employments.adoc |   5 +-
 .../docs/asciidoc/_include/hr-global-settings.adoc |  50 +++++++++
 .../src/docs/asciidoc/_include/hr-glossary.adoc    |  28 ++---
 .../src/docs/asciidoc/_include/hr-intro.adoc       | 108 ++++++++++--------
 .../humanres/src/docs/asciidoc/humanres.adoc       |  48 +++++---
 .../asciidoc/images/hr-data-model/EmplPosition.png | Bin 0 -> 124686 bytes
 .../images/hr-data-model/EmplPositionDetail.png    | Bin 0 -> 74561 bytes
 docs/asciidoc/images/hr-data-model/Employment.png  | Bin 0 -> 108260 bytes
 .../images/hr-data-model/EmploymentApp.png         | Bin 0 -> 94205 bytes
 .../images/hr-data-model/PartyHumanRes.png         | Bin 0 -> 148349 bytes
 docs/asciidoc/images/hr-data-model/PerfReview.png  | Bin 0 -> 64103 bytes
 docs/asciidoc/images/hr-data-model/ability.png     | Bin 0 -> 93714 bytes
 15 files changed, 386 insertions(+), 84 deletions(-)

diff --git a/applications/humanres/src/docs/asciidoc/_include/hr-appendix.adoc b/applications/humanres/src/docs/asciidoc/_include/hr-appendix.adoc
new file mode 100644
index 0000000..90c5b6c
--- /dev/null
+++ b/applications/humanres/src/docs/asciidoc/_include/hr-appendix.adoc
@@ -0,0 +1,77 @@
+////
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements.  See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership.  The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License.  You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied.  See the License for the
+specific language governing permissions and limitations
+under the License.
+////
+
+[appendix]
+= HR Data Model Resource Book Difference
+
+PayHistory:: it's not really a difference, more a not explicit detail about fromDate field. +
+PayHistory is a detail of Employment entity (Composition in UML language) and Employment entity has a fromDate field
+(as one of the keyField), and we need fromDate field for information about PayHistory, so it's needed to have one named
+emplFromDate (coming from Employment) and one classical fromDate to be able to have multiple PayHistory for one Employment.
+
+PartyBenefit:: It's exactly the same problem or case than PayHistory, currently in Apache OFBiz entity is exactly the same
+as in Data Model Resource Book Difference (only one fromDate field), so it's not possible to have a correct User Interface
+as an Employment subOption. +
+So correct solution should be to have one more field: emplFromDate (coming from Employment).
+
+Resume:: entity in Apache OFBiz is a simplification of the concept explain in the Book
+
+[appendix]
+= HR Enhancement & Bug
+== Functional bug
+This section explain current "Bug" which are waiting some developpment.
+
+=== CreateEmployee
+Currently create an employee should create a Party Relationship between Employer and Employee(cf <<_employments, documentation>>),
+it's not working because a parameters if forgot in service but it's not the major "Bug", and the main question is : +
+create an employee should create a Party Relationship or a Employment (which is a subtype of PartyRelationship) ?
+
+If the create Employee screen is used from HR, it's to use HR functions and for HR component, an employee has an Employment
+(which is a subtype of PartyRelationship), so create an Employee should create an Employment (and so the first PayHistory). +
+Screen and Service should corrected to do these points.
+
+
+
+== Functional Enhancement
+This section explain which developpment should be done to add some features which should be in Apache OFBiz
+
+=== Valid Responsibility
+Entity ValidResponsibility exist in Apache OFBiz, associated controler screens, forms and services exists too,
+but there is no menu to use them !
+
+. Add a entry menu in Employee Position Type sub menu (in Global HR Setting)
+. Correction on screen definition to included GlobalHR decorator and button highlight
+
+JIRA OFBIZ-11045 is for that.
+
+==== Business Rule
+It's suggest in «the Data Model Resource Book» to have a check before adding some responsibilities to a job Position
+if Position Type has it (in ValidResposibility) with valid date.
+
+=== Position Type Rate amount-and-grade
+For a RateType, it should not be possible to have a amount AND a Grade-Step.
+
+=== EmplPositionTypeClass
+Entity exist but no screen management.
+
+Same for EmplPositonClassType
+
+=== BenefitType
+Entity exist but no screen management. +
+It should be place in Global HR Settings
diff --git a/applications/humanres/src/docs/asciidoc/_include/hr-data-model.adoc b/applications/humanres/src/docs/asciidoc/_include/hr-data-model.adoc
new file mode 100644
index 0000000..94c0d66
--- /dev/null
+++ b/applications/humanres/src/docs/asciidoc/_include/hr-data-model.adoc
@@ -0,0 +1,123 @@
+////
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements.  See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership.  The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License.  You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied.  See the License for the
+specific language governing permissions and limitations
+under the License.
+////
+= HR Data model
+
+This chapter describe the main entities for the Human Resource Component. +
+The goal is to show :
+
+* overall view for each HR core object
+* link between entities
+
+For each diagram, Main Entities (for this diagram) are in purple +
+Entities in Light Blue have not all fields (link, composition ) present.
+
+== Employee Position
+[#DATAMODEL-EMPL-POSITION]
+=== Position and PositionType
+This diagram explain Position and PositionType main informations.
+image:hr-data-model/EmplPosition.png[Employee Position, float="right"]
+
+==== Diagram associated
+* <<DATAMODEL-EMPL-POSITION-DETAIL, Position details>>
+* <<DATAMODEL-PARTY-HUMANRES, Party in Human Resources>>
+* <<DATAMODEL-EMPLOYMENT, Employment>>
+* <<DATAMODEL-EMPLOYMENT-APPL, Employment Appl>>
+* <<DATAMODEL-ABILITY, Qualification Skill training>>
+* <<DATAMODEL-PERFORMANCE-REVIEW, Performance Review>>
+
+[#DATAMODEL-EMPL-POSITION-DETAIL]
+=== Position details
+This diagram show all Positions main informations / link.
+image:hr-data-model/EmplPositionDetail.png[Employee Position Detail, width=90%, float="right"]
+
+==== Diagram associated
+* <<DATAMODEL-EMPL-POSITION, Position and PositionType>>
+* <<DATAMODEL-PARTY-HUMANRES, Party in Human Resources>>
+* <<DATAMODEL-EMPLOYMENT, Employment>>
+* <<DATAMODEL-EMPLOYMENT-APPL, Employment Appl>>
+* <<DATAMODEL-ABILITY, Qualification Skill training>>
+* <<DATAMODEL-PERFORMANCE-REVIEW, Performance Review>>
+
+== Employment
+[#DATAMODEL-EMPLOYMENT]
+=== Employment
+This diagram explain Position and PositionType main informations.
+image:hr-data-model/Employment.png[Employment, float="right"]
+
+==== Diagram associated
+* <<DATAMODEL-EMPL-POSITION, Position and PositionType>>
+* <<DATAMODEL-EMPL-POSITION-DETAIL, Position details>>
+* <<DATAMODEL-PARTY-HUMANRES, Party in Human Resources>>
+* <<DATAMODEL-EMPLOYMENT-APPL, Employment Appl>>
+* <<DATAMODEL-ABILITY, Qualification Skill training>>
+* <<DATAMODEL-PERFORMANCE-REVIEW, Performance Review>>
+
+[#DATAMODEL-EMPLOYMENT-APPL]
+=== Employment Appl
+This diagram show all Positions main informations / link.
+image:hr-data-model/EmploymentApp.png[Employment Appl, width=90%, float="right"]
+
+==== Diagram associated
+* <<DATAMODEL-EMPL-POSITION, Position and PositionType>>
+* <<DATAMODEL-EMPL-POSITION-DETAIL, Position details>>
+* <<DATAMODEL-PARTY-HUMANRES, Party in Human Resources>>
+* <<DATAMODEL-EMPLOYMENT, Employment>>
+* <<DATAMODEL-ABILITY, Qualification Skill training>>
+* <<DATAMODEL-PERFORMANCE-REVIEW, Performance Review>>
+
+== Qualification, Skill, Review
+[#DATAMODEL-ABILITY]
+=== Training
+This diagram show all link between Party & PartyRole  AND all HR entites.
+image:hr-data-model/ability.png[Training, width=90%, float="right"]
+
+==== Diagram associated
+* <<DATAMODEL-EMPL-POSITION, Position and PositionType>>
+* <<DATAMODEL-EMPL-POSITION-DETAIL, Position details>>
+* <<DATAMODEL-PARTY-HUMANRES, Party in Human Resources>>
+* <<DATAMODEL-EMPLOYMENT, Employment>>
+* <<DATAMODEL-EMPLOYMENT-APPL, Employment Appl>>
+* <<DATAMODEL-PERFORMANCE-REVIEW, Performance Review>>
+
+[#DATAMODEL-PERFORMANCE-REVIEW]
+=== Performance Review
+This diagram show all link between Party & PartyRole  AND all HR entites.
+image:hr-data-model/PerfReview.png[Performance Review, width=90%, float="right"]
+
+==== Diagram associated
+* <<DATAMODEL-EMPL-POSITION, Position and PositionType>>
+* <<DATAMODEL-EMPL-POSITION-DETAIL, Position details>>
+* <<DATAMODEL-PARTY-HUMANRES, Party in Human Resources>>
+* <<DATAMODEL-EMPLOYMENT, Employment>>
+* <<DATAMODEL-EMPLOYMENT-APPL, Employment Appl>>
+* <<DATAMODEL-ABILITY, Qualification Skill training>>
+
+== HR App intra-application integration
+[#DATAMODEL-PARTY-HUMANRES]
+=== Party in Human Resources
+This diagram show all link between Party & PartyRole  AND all HR entites.
+image:hr-data-model/PartyHumanRes.png[Party in Human Resources, width=90%, float="right"]
+
+==== Diagram associated
+* <<DATAMODEL-EMPL-POSITION, Position and PositionType>>
+* <<DATAMODEL-EMPL-POSITION-DETAIL, Position details>>
+* <<DATAMODEL-EMPLOYMENT, Employment>>
+* <<DATAMODEL-EMPLOYMENT-APPL, Employment Appl>>
+* <<DATAMODEL-ABILITY, Qualification Skill training>>
+* <<DATAMODEL-PERFORMANCE-REVIEW, Performance Review>>
diff --git a/applications/humanres/src/docs/asciidoc/_include/hr-employee-positions.adoc b/applications/humanres/src/docs/asciidoc/_include/hr-employee-positions.adoc
index 1b6d4b9..a14efb0 100644
--- a/applications/humanres/src/docs/asciidoc/_include/hr-employee-positions.adoc
+++ b/applications/humanres/src/docs/asciidoc/_include/hr-employee-positions.adoc
@@ -19,7 +19,10 @@ under the License.
 = Employee Positions
 An employee position is also called a job position. It is a role that has been
 created to perform a specific task within the Company. This means that it has
-approved funding to pay it.
+approved funding to pay it. +
+Generally positions are authorized by a budget and fulfilled by people.
+For the Company to engage one person to do a job. OFBiz handles positions in a flexible manner
+ so you can think of a position as an authorization for a full-time equivalent (FTE)
 
 Employee positions are defined by:
 
@@ -37,13 +40,27 @@ role) or it can be unfulfilled (i.e. a job vacancy).
 NOTE: In some cases an employee position could also be considered a full-time
  equivalent (FTE) and can be assigned to more than one person (e.g. job sharing)
 
-In the OFBiz Human Resources application you can:
+In the OFBiz Human Resources application
+
+* an employee position have
+** a type, defined in Global HR Settings, which describes the job and it's pay rates. +
+   Some examples types could be secretary, production worker, sales manager, executive vice president or OFBiz programmer. +
+   If more then one person is needed for a type of job then a position must be created for each required person :
+   i.e. If 10 secretaries are authorized for the Human Resource department then 10 positions are created with type secretary.
+** a reporting structure.  Positions report to other positions and not the people who hold the position. +
+   You can identify / manage
+*** the position to reports to
+*** the positions(s), the current position manages.
+*** in matrix orgnaization when there are multiple positions to report, most of time only one is the primary for the day to day
+    approval (like holidays). It's the purpose of the flag primary
+** a status, it can be one of: Planned For, Active/Open, or Inactive/Closed.
+* you can:
+** Create employee positions
+** Fulfill employee positions
+** Define the responsibilities of an employee position
+** Define a tree reporting structure between employee positions
+** Track employment position fulfillments over time
 
-* Create employee positions
-* Fulfill employee positions
-* Define the responsibilities of an employee position
-* Define a tree reporting structure between employee positions
-* Track employment position fulfillments over time
 
 == Employee Position management in UI
 === List Employee Position
diff --git a/applications/humanres/src/docs/asciidoc/_include/hr-employments.adoc b/applications/humanres/src/docs/asciidoc/_include/hr-employments.adoc
index cb5c642..75a19ea 100644
--- a/applications/humanres/src/docs/asciidoc/_include/hr-employments.adoc
+++ b/applications/humanres/src/docs/asciidoc/_include/hr-employments.adoc
@@ -22,7 +22,7 @@ An employment is a relationship between a person and your Company.
 The Human Resources application tracks employment benefits, pay history,
 unemployment claims and employment agreements for each employed person.
 
-When you create new employee, an employee relationship is created automatically.
+When you create new employee, an employee relationship is created automatically (/!\ see <<_createemployee>> functional Bug).
 
 NOTE: If a person was entered into the application by some other means then you
 will have to create the employee relationship manually in the Party Manager application.
@@ -35,6 +35,9 @@ For example, an employee may have been let go because of poor performance.
 The Employments screen can be used to create an employment or search for existing
 employments.
 
+To other explanation, look at the process <<_employee_salary_and_benefits_administration>> introduction. +
+A Database diagram for main link with other entities exist in <<DATAMODEL-EMPLOYMENT, HR Data model - Employment>>
+
 == Employments management in UI
 
 === Create or Edit Employment
diff --git a/applications/humanres/src/docs/asciidoc/_include/hr-global-settings.adoc b/applications/humanres/src/docs/asciidoc/_include/hr-global-settings.adoc
index a10b88e..1aa7305 100644
--- a/applications/humanres/src/docs/asciidoc/_include/hr-global-settings.adoc
+++ b/applications/humanres/src/docs/asciidoc/_include/hr-global-settings.adoc
@@ -26,6 +26,56 @@ here.
 TIP: You need to have 'administrator' or 'create privileges' to update any of
 the Global HR Settings
 
+== Employee Leave Type
+Used by <<_leave, Employee Leave>> management to detail why is employee request a leave.
+
+In this menu option you could manage (create / modify / delete) Leave Type and Leave Reason.
+
+For some example, look at the Tutorial Employment and Salary <<_step_5_employee_leaves>>
+
+=== Reason Type
+To create or request a leave an employee could give the type of leave and the reason.
+
+== Pay Grades
+Useful to define a salary amount table for the company. With this table for each grade and a step
+you have a amount.
+
+It's used in structured entreprise to be more clear on salary definition or supplier cost.
+
+Worksheet PayGrade - SalaryStep is not usable alone, when it's used to define a <<_rates>> it's associated
+with PeriodType (per year, per month, per week, per hour) and RateType (Standard, Average, Hightest, lowest, ...). +
+So sometine it's needed to define multiple Grades if it will be use with a specifics periodType,
+ex: for developper, one Grade for using with «per month» and one Grade for using with «per hours»
+
+=== Salary Steps
+For each Grade, it possible to have multiple step. It's possible to have overlap in step betwwen to grade.
+
+For more detail, look at the Tutorial Employment and Salary <<_step_1_pay_grade_and_salary_step>>
+
+
+== Position Types
+<<_employee_positions>> is associated with a Position Type to "pre-define" some informations about the Job Position.
+
+Position Type can be use for legal purpose, like social classification or Union constrain to be able "classify" Job position.
+
+=== Position Type Rate
+When defining a Employee Position, Salary is one of the important point. Depending of company salary rules, most of time
+there is not a salary associated with a Position but a range and some indicators.
+
+So it's possible to associated to a position type some amount associated to a Rate Type (Standard, Average, Hightest, lowest, …​)
+and a  PeriodType (per year, per month, per week, per hour).
+
+It's also used by WorkEffort Component to manage cost for subcontractor, for example.
+
+=== Position Type Grade
+If company is very structured on the salary management and so mange Salary by <<_pay_grades, Grade-Step>>, it's possible to
+associate a Position Type and a RateType a Grade-Step.
+
+As business rules, it's not possible to have for the same RateType a amount and a Grade-Step.
+
+=== Valid Responsibilities
+It's possible to define some responsibilities for a Position Type, to constrain the responsibilities it is authorized to
+associate to a Employee Position (which is associated to this Position Type).
 
 == Skills Types
 
diff --git a/applications/humanres/src/docs/asciidoc/_include/hr-glossary.adoc b/applications/humanres/src/docs/asciidoc/_include/hr-glossary.adoc
index 996676c..a9d0d0b 100644
--- a/applications/humanres/src/docs/asciidoc/_include/hr-glossary.adoc
+++ b/applications/humanres/src/docs/asciidoc/_include/hr-glossary.adoc
@@ -16,7 +16,8 @@ KIND, either express or implied.  See the License for the
 specific language governing permissions and limitations
 under the License.
 ////
-= Glossary
+[glossary]
+= HR Glossary
 
 [#BUDGET]
 Budget::
@@ -27,12 +28,13 @@ items.
 
 [#EMPLOYEE]
 Employee::
-An employee is a person who has an employment relationship with your Company.
+An employee is a person who has an employment relationship with your Company. +
+For more detail see <<_employees>> chapter.
 
 [#EMPLOYEE_POSITION_TYPE]
 Employee Position Type::
-Employee Positions Type is a name that describes a position. Business Analyst,
- Programmer and System Administrator are examples of position types in the OFBiz
+Employee Position Type is a name that describes a position (<<_employee_positions, Employee Positions>>).
+Business Analyst, Programmer and System Administrator are examples of position types in the OFBiz
 demo data. You can define your own position types in Global HR Settings > Position
 Types.
 
@@ -40,7 +42,14 @@ Types.
 Employment::
 Employment defines the relationship between your Company and a person who is an
  employee. The employment relationship tracks employee benefits  preferences, pay
-history, and unemployment claims and agreements.
+history, and unemployment claims and agreements. +
+For more detail see <<_employments>> chapter.
+
+[#BENEFITS]
+Employment Benefits::
+Employment imply salary but not only, most of time, there are some benefit packages associated. Examples are
+vacation,health or life insurance, sick leave or retirement plan. Cost of these package may be partly or completely
+paid by the entreprise. Example can be see in <<_step_4_employee_associated_benefits>> in <<_tutorial_employment_and_salary>>.
 
 [#EXEMPT_FLAG]
 Exempt Flag::
@@ -110,15 +119,6 @@ Human beings and organizations have different attributes i.e. People have first
 last names while groups have group names. Both person and party group are types
  of parties and share information and processes common to parties.
 
-[#POSITION]
-Position::
-A position is a job that can be filled by more then one person over time or at
-the same time. Positions are defined by a type of work. For example there may
-be 20 positions in an organization for a secretary. Each position is related to
-a department in the organization. A position can me thought of as a full-time
-equivalent employee (FTE). So an FTE may be assigned to one or more positions
-and position can be assigned to more then one FTEs (job sharing).
-
 [#RATING]
 Rating::
 Rating is a user defined numeric rating for a skill. (See Skills Menu)
diff --git a/applications/humanres/src/docs/asciidoc/_include/hr-intro.adoc b/applications/humanres/src/docs/asciidoc/_include/hr-intro.adoc
index ae1b39a..7ce2685 100644
--- a/applications/humanres/src/docs/asciidoc/_include/hr-intro.adoc
+++ b/applications/humanres/src/docs/asciidoc/_include/hr-intro.adoc
@@ -31,63 +31,73 @@ building that platform.
 
 include::HELP-hr-main.adoc[leveloffset=+1]
 
-= Human Resources Processes
+= HR Processes
 
 Human Resources Management can be divided into several distinct processes.
 
-* Job Planning and Definition
-* Recruitment
-* Candidate Selection and Hiring
-* Employee Training and Development
-* Employee Evaluation and Performance Management
-* Employee Salary and Benefits
+* <<_organization_job_position_and_definition>>
+* <<_employee_training_and_development>>
+* <<_performance_management_and_employee_evaluation>>
+* <<_employee_salary_and_benefits_administration>>
+* <<_recruitment_candidate_selection_and_hiring>>
 
-== Job Planning and Definition
+== Organization, Job Position and Definition
 
-Generally job positions are authorised by a budget and fulfilled by people. The
+Many companies organize departments in a tree structure.
+There is no special meaning attached to the word department. +
+It is used to describe any sub-division of a business organization.
+
+In each department there are some <<_employee_positions, Employee positions>> (or Job position) +
+Generally <<_employee_positions, Job positions>> are authorized by a budget and fulfilled by people. The
  person fulfilling the position may be a permanent employee, a temporary employee
 or a contractor.
 
-* Positions may be salary or hourly, fulltime or part time.
+* Positions may be salary or hourly, full-time or part time.
 * Positions have responsibilities.
 * Positions are defined by a type of work.
 
-For example there may be 20 job positions in an organization for a administrative
-clerk. Each position is has a job definition and is authorised by a budget request
-from a department in the organization.
-A position can be unfulfilled. (i.e a it exists but no one is currently employed
-to do it).
-In some cases a position could also be considered a full-time equivalent (FTE) and
-can be assigned to more than one person (e.g. job sharing)
+Your Companies organizational tree is shown on the main page of the HR App, and you can manage each part of it
+(view, add, remove departments; assign job position to department or manage its <<EMPLOYMENT, employments>>)
 
-In the OFBiz Human Resources application you can:
+If you need to define one or more department, you must create it in the Party component. +
+Create a Party-Group and associated to it the role type Internal Organization (INTERNAL_ORGANIZATIO).
+After that the department appear in the drop-down when you select "Add Internal Organization" in the contextual menu
+(click right) of the Companies organizational tree in HR component.
 
-* Create positions
-* Fulfill positions
-* Define the responsibilities of a position
-* Define a tree reporting structure between positions
-* Track the positions fulfillments over time
+If you need to define one or more <<_employee_positions, Job positions>>, you must create it in the Employee Position
+ HR sub-component ( Main HR Menu, option Employee Position) and maybe previously create some <<EMPLOYEE_POSITION_TYPE, Position Type>>
+ in Global HR Settings HR sub-component.
 
-== Recruitment, Candidate Selection and Hiring
 
-Recruitment is about at attracting applicants that match the skills and experience
- you are looking for in a particular job position. Candidates can apply and after
-reviewing their details, those who are the best match in terms of qualifications
-and experience are short listed for interview. The final step is deciding upon the
- final candidate that you want to hire and the employment contract details that
-are related to that.
+== Employee Salary and Benefits Administration
 
-In the OFBiz Human Resouces application you can:
+Being able to manage employee salaries and associated benefits is a key part of
+any Human Resources system.
+
+Salary is *not* related to a <<_employee_positions>> (also named Job Position) because when
+a person which fulfill a Job Position change to an other, salary does'nt change in every time. Some organization
+are waiting person demonstrate his capabilities for the new Job Position to change salary.
+
+Salary is *not* related only to a Person, because in some company there are multiple subsidiaries or affiliate company,
+so Salary (and associated benefits) is related to <<_employments>> (a subtype of Party Relationship).
+
+In hightly structured company, Salary is organized with a pay schedule which have normally two level <<_pay_grades, Grade and step>>. +
+In Apache OFBiz, you can manage salary (and other point) directly by amount or with <<_pay_grades, Grade-Step>> or with a mix of them.
+
+In the OFBiz Human Resources application you can:
+
+* Create Pay Grades and Salary Steps within each Pay Grade
+* Assign a Pay Grade and Salary Step to a Job Position Type
+* Manage Employment and
+** his Pay History
+** his associated Benefits
+** his Leaves (Holidays, ill, family event,..)
+* Calculate salaries and Generate Payslips
 
-* Create a Requisition for new job positions
-* Create Internal Job Postings
-* Apply for job positions
-* Review Resumes / CVs
-* Arrange and Grade Interviews
 
 == Employee Training and Development
 
-Training and professional development is important for an organisation because it
+Training and professional development is important for an organization because it
 ensures that your employees have the knowledge they need to perform their work.
 It can also help to fill any gaps in skills and improve their proficiency.
 
@@ -114,19 +124,21 @@ In the OFBiz Human Resources application you can:
 If an evaluation has gone well then the employee can be considered for promotion
 to another job position, or can be given other benefits such as a salary increase.
 
-== Employee Salary and Benefits Administration
+== Recruitment, Candidate Selection and Hiring
 
-Being able to manage employee salaries and associated benefits is a key part of
-any Human Resources system.
+Recruitment is about at attracting applicants that match the skills and experience
+ you are looking for in a particular job position. Candidates can apply and after
+reviewing their details, those who are the best match in terms of qualifications
+and experience are short listed for interview. The final step is deciding upon the
+ final candidate that you want to hire and the employment contract details that
+are related to that.
 
 In the OFBiz Human Resources application you can:
 
-* Create Pay Grades
-* Link Salary Steps within each Pay Grade
-* Assign a Pay Grade and Salary Step to a Job Position filled by an Employee
-* Manage employee holidays (leave)
-* Manage associated benefits
-* Calculate salaries and Generate Payslips
-
-
+* Create a Requisition for new job positions
+* Create Internal Job Postings
+* Apply for job positions
+* Review Resumes / CVs
+* Arrange and Grade Interviews
 
+(add a test to check if createEmployment works for not yet employee (ex: party which are before only candidat)
diff --git a/applications/humanres/src/docs/asciidoc/humanres.adoc b/applications/humanres/src/docs/asciidoc/humanres.adoc
index fc8ef2b..bbb0217 100644
--- a/applications/humanres/src/docs/asciidoc/humanres.adoc
+++ b/applications/humanres/src/docs/asciidoc/humanres.adoc
@@ -19,34 +19,54 @@ under the License.
 = Human Resources
 
 The OFBiz Human Resources system is one of the <<CORE_APPLICATION_COMPONENTS,core application components>> and has
-all of the functionality you need to manage your business <<EMPLOYEE,employees>> as well as the
-recruitment process. It is well integrated with other components especially
-Accounting to manage Payroll and any specific  employee agreements.
+all of the functionality you need to manage your business <<EMPLOYEE,employees>> process :
+organisational hierarchies, recruitment, training, evaluation, ...
+It is well integrated with other components especially
+ Accounting to manage Payroll and any specific  employee agreements.
+
+The HR Application data design, like most of the OFBiz back office administration applications, was inspired by
+the data models in The Data Model Resource Books by Len Silverston
+footnote:ref:[silverston-data-model, http://silverston.wiley.com/index.html[Silverston Data Model Resource Companion Site]].
+The sections below introduces some of the concepts in HR App that were derived from the models.
+
+In OFBiz <<PARTY, Party>> is one of the core object, a party is a person (employee, end customer, sub-contractor, contact, ...)
+or an organization (group, department, company, ...). +
+One of the strengths of OFBiz is the rich set of features it has build up to manage information and relationships for parties.
+This makes OFBiz a great platform for HR services because managing people and organizations is a core OFBiz technology.
+
+Important terms in the documentation are defined in a Glossary. In order to promote a consistent usage
+and understanding of terms, links to the Glossary definitions are placed throughout the document.
 
 include::_include/hr-intro.adoc[leveloffset=+1]
 
-include::_include/hr-employee-positions.adoc[leveloffset=+1]
+== HR core object
 
-include::_include/hr-employees.adoc[leveloffset=+1]
+include::_include/hr-employee-positions.adoc[leveloffset=+2]
 
-include::_include/hr-employments.adoc[leveloffset=+1]
+include::_include/hr-employees.adoc[leveloffset=+2]
 
-include::_include/hr-performance-review.adoc[leveloffset=+1]
+include::_include/hr-employments.adoc[leveloffset=+2]
 
-include::_include/hr-qualifications.adoc[leveloffset=+1]
+include::_include/hr-performance-review.adoc[leveloffset=+2]
 
-include::_include/hr-recruitment.adoc[leveloffset=+1]
+include::_include/hr-qualifications.adoc[leveloffset=+2]
 
-include::_include/hr-skills.adoc[leveloffset=+1]
+include::_include/hr-recruitment.adoc[leveloffset=+2]
 
-include::_include/hr-resumes.adoc[leveloffset=+1]
+include::_include/hr-skills.adoc[leveloffset=+2]
 
-include::_include/hr-training.adoc[leveloffset=+1]
+include::_include/hr-resumes.adoc[leveloffset=+2]
 
-include::_include/hr-leave.adoc[leveloffset=+1]
+include::_include/hr-training.adoc[leveloffset=+2]
 
-include::_include/hr-security.adoc[leveloffset=+1]
+include::_include/hr-leave.adoc[leveloffset=+2]
+
+include::_include/hr-security.adoc[leveloffset=+2]
 
 include::_include/hr-global-settings.adoc[leveloffset=+1]
 
+include::_include/hr-data-model.adoc[leveloffset=+1]
+
 include::_include/hr-glossary.adoc[leveloffset=+1]
+
+include::_include/hr-appendix.adoc[leveloffset=+1]
diff --git a/docs/asciidoc/images/hr-data-model/EmplPosition.png b/docs/asciidoc/images/hr-data-model/EmplPosition.png
new file mode 100644
index 0000000..1ad4228
Binary files /dev/null and b/docs/asciidoc/images/hr-data-model/EmplPosition.png differ
diff --git a/docs/asciidoc/images/hr-data-model/EmplPositionDetail.png b/docs/asciidoc/images/hr-data-model/EmplPositionDetail.png
new file mode 100644
index 0000000..a3b6a52
Binary files /dev/null and b/docs/asciidoc/images/hr-data-model/EmplPositionDetail.png differ
diff --git a/docs/asciidoc/images/hr-data-model/Employment.png b/docs/asciidoc/images/hr-data-model/Employment.png
new file mode 100644
index 0000000..c5900e9
Binary files /dev/null and b/docs/asciidoc/images/hr-data-model/Employment.png differ
diff --git a/docs/asciidoc/images/hr-data-model/EmploymentApp.png b/docs/asciidoc/images/hr-data-model/EmploymentApp.png
new file mode 100644
index 0000000..9cfa830
Binary files /dev/null and b/docs/asciidoc/images/hr-data-model/EmploymentApp.png differ
diff --git a/docs/asciidoc/images/hr-data-model/PartyHumanRes.png b/docs/asciidoc/images/hr-data-model/PartyHumanRes.png
new file mode 100644
index 0000000..cc5918b
Binary files /dev/null and b/docs/asciidoc/images/hr-data-model/PartyHumanRes.png differ
diff --git a/docs/asciidoc/images/hr-data-model/PerfReview.png b/docs/asciidoc/images/hr-data-model/PerfReview.png
new file mode 100644
index 0000000..6ed7647
Binary files /dev/null and b/docs/asciidoc/images/hr-data-model/PerfReview.png differ
diff --git a/docs/asciidoc/images/hr-data-model/ability.png b/docs/asciidoc/images/hr-data-model/ability.png
new file mode 100644
index 0000000..c2c253f
Binary files /dev/null and b/docs/asciidoc/images/hr-data-model/ability.png differ