Bxmsdoc 3092 3206 master (#21)

* most work done on both Rostering docs

* more information on building etc

* SME review

* finishing SME revire

* SME and QE review changes

* peer review results

* removed s2i

_artifacts/document-attributes.adoc

@@ -36,7 +36,6 @@ endif::OP[]
 // For copyright
 :YEAR: 2018
 
-// Maven info, from https://mvnrepository.com (public repo) or https://repository.jboss.org/nexus/index.html#welcome (Nexus repo)
 :MAVEN_ARTIFACT_VERSION: 7.11.0.Final-redhat-00002
 :BOM_VERSION: 7.1.0.GA-redhat-00002
 

assemblies/assembly_business-optimizer-ER-sample-openshift/main.adoc

@@ -2,7 +2,7 @@
 
 include::_artifacts/document-attributes.adoc[]
 
-= Running the employee roster starter application for {PLANNER} on {OPENSHIFT}
+= Deploying and running the employee roster starter application for {PLANNER} on {OPENSHIFT}
 // Context attribute is assembly specific and enables module reuse between assemblies.
 :doctype: book
 :imagesdir: _images
@@ -14,12 +14,29 @@ include::_artifacts/author-group.adoc[]
 As a business rules developer, you can test and interact with the {PLANNER} functionality by quickly deploying the `employee-rostering` starter project included in the {PRODUCT} distribution to OpenShift.
 
 .Prerequisites
-* You have downloaded the {PRODUCT} add-ons distribution,  which includes the OptaShift Employee Rostering starter application.
 * You have access to a deployed OpenShift environment. For details, see the documentation for the OpenShift product that you use.
 
 // Modules - concepts, procedures, refs, etc.
-include::{enterprise-dir}/employee-rostering/optashift-ER-openshift-deploy-proc.adoc[leveloffset=+1]
 include::{enterprise-dir}/employee-rostering/optashift-ER-overview-con.adoc[leveloffset=+1]
+include::{enterprise-dir}/employee-rostering/optashift-ER-openshift-deploy-con.adoc[leveloffset=+1]
+include::{enterprise-dir}/employee-rostering/er-deploy-prepare-proc.adoc[leveloffset=+2]
+include::{enterprise-dir}/employee-rostering/er-deploy-script-proc.adoc[leveloffset=+2]
+include::{enterprise-dir}/employee-rostering/er-using-con.adoc[leveloffset=+1]
+include::{enterprise-dir}/employee-rostering/er-periods-con.adoc[leveloffset=+2]
+include::{enterprise-dir}/employee-rostering/er-rotation-con.adoc[leveloffset=+2]
+include::{enterprise-dir}/employee-rostering/er-tenants-con.adoc[leveloffset=+2]
+include::{enterprise-dir}/employee-rostering/er-tenant-select-proc.adoc[leveloffset=+3]
+include::{enterprise-dir}/employee-rostering/er-tenant-create-proc.adoc[leveloffset=+3]
+include::{enterprise-dir}/employee-rostering/er-skills-proc.adoc[leveloffset=+2]
+include::{enterprise-dir}/employee-rostering/er-spots-proc.adoc[leveloffset=+2]
+include::{enterprise-dir}/employee-rostering/er-employees-proc.adoc[leveloffset=+2]
+include::{enterprise-dir}/employee-rostering/er-availability-proc.adoc[leveloffset=+2]
+include::{enterprise-dir}/employee-rostering/er-shiftroster-proc.adoc[leveloffset=+2]
+include::{enterprise-dir}/employee-rostering/er-solve-proc.adoc[leveloffset=+2]
+include::{enterprise-dir}/employee-rostering/er-individualroster-proc.adoc[leveloffset=+2]
+include::{enterprise-dir}/employee-rostering/er-publish-proc.adoc[leveloffset=+2]
+include::{enterprise-dir}/employee-rostering/er-rotation-edit-proc.adoc[leveloffset=+2]
+
 
 // Versioning info
 include::_artifacts/versioning-information.adoc[]

assemblies/assembly_business-optimizer-modifying-ER-template-IDE/main.adoc

@@ -14,18 +14,20 @@ include::_artifacts/author-group.adoc[]
 As a business rules developer, you can use an IDE to build, run, and modify the 'employee-rostering' starter application that uses the {PLANNER} functionality.
 
 .Prerequisites
-* {PRODUCT} "add-ons" distribution has been downloaded which includes the 'employee-rostering' starter application
-* An indegrated development environment, such as Eclipse (including Red Hat JBoss Developer Studio) or IntelliJ IDEA.
+* An integrated development environment, such as Eclipse (including Red Hat JBoss Developer Studio) or IntelliJ IDEA.
 * An understanding of the Java language
 
 // Modules - concepts, procedures, refs, etc.
 include::{enterprise-dir}/employee-rostering/optashift-ER-overview-con.adoc[leveloffset=+1]
 include::{enterprise-dir}/employee-rostering/optashift-ER-building-con.adoc[leveloffset=+1]
+include::{enterprise-dir}/employee-rostering/er-deploy-prepare-proc.adoc[leveloffset=+2]
 include::{enterprise-dir}/employee-rostering/optashift-ER-building-commandline-proc.adoc[leveloffset=+2]
+include::{enterprise-dir}/employee-rostering/optashift-ER-building-commandline-db-proc.adoc[leveloffset=+2]
+include::{enterprise-dir}/employee-rostering/optashift-ER-building-eclipse-proc.adoc[leveloffset=+2]
 include::{enterprise-dir}/employee-rostering/optashift-ER-overview-source-con.adoc[leveloffset=+1]
 include::{enterprise-dir}/employee-rostering/optashift-ER-modifying-proc.adoc[leveloffset=+1]
-include::{enterprise-dir}/employee-rostering/optashift-ER-modifying-sample-weekend-proc.adoc[leveloffset=+2]
-include::{enterprise-dir}/employee-rostering/optashift-ER-modifying-sample-gender-proc.adoc[leveloffset=+2]
+// include::{enterprise-dir}/employee-rostering/optashift-ER-modifying-sample-weekend-proc.adoc[leveloffset=+2]
+// sample dropped for 7.1 GA as Christopher could not get it to work because of an apparent Drools bug
 
 // Versioning info
 include::_artifacts/versioning-information.adoc[]

doc-content/enterprise-only/employee-rostering/er-availability-proc.adoc

@@ -0,0 +1,22 @@
+[id='er-availability-proc']
+= Setting employee availability
+
+You can set the availability of employees for particular time spans. 
+
+If an employee is _unavailable_ for a particular time span, the employee can never be assigned to any shift during this time span (for example, if the employee has called in sick or is on vacation). _Undesired_ and _desired_ are employee preferences for particular time spans; the application accommodates them when possible.
+
+.Procedure
+. To view and edit employee availability, click the *Availability Roster* tab.
+. In the top right part of the browser window, the *Week of* field lists the week for which the roster is displayed. To view other weeks, use the *<* and *>* buttons next to the *Week of* field. Alternatively, click on the date field and change the date to view the week that includes this date.
+. If the list is longer than 10 employees, the numbers of currently visible employees are displayed in the top right part of the browser window, for example, `1-15 of 34`. Use the *<* and *>* buttons next to the numbers to display other employees in the list. 
+. To create an availability entry for an employee, click empty space on the intersection of a date (column) and an employee (row). Initially, an `Unavailable` entry for the entire day is created.
+. To change an availability entry, double-click the entry. You can change the following settings:
+** *From* and *To* date and time: The time span to which the availability entry applies.
+** Status: you can select *Unavailable*, *Desired*, or *Undesired* status from a drop-down list.
++
+To save the entry, click *Apply*.
+. To delete an availability entry, double-click the entry, then click *Delete availability*.
+
+IMPORTANT: If an employee is already assigned to a shift and then you create or change an availability entry during this shift, the assignment is not changed automatically. You must create the employee roster again to apply new or changed availability entries.  
+
+

doc-content/enterprise-only/employee-rostering/er-deploy-prepare-proc.adoc

@@ -0,0 +1,15 @@
+[id='er-deploy-prepare-proc']
+= Preparing deployment files
+
+You must download and prepare the deployment files before building and deploying the application.
+
+.Procedure
+
+. Download the `{PRODUCT_FILE}-add-ons.zip` file from the {PRODUCT_DOWNLOAD_LINK}[Software Downloads] page for {PRODUCT} {PRODUCT_VERSION}.
+. Unzip the downloaded archive.
+. Unzip the employee rostering zip file (`{PRODUCT_FILE}-employee-rostering.zip`) that is extracted from the add-ons archive.
+
+.Result
+When you unzip the employee rostering zip file, the `optashift-employee-rostering-{MAVEN_ARTIFACT_VERSION}` folder is created. This folder is the base folder in subsequent steps. 
+
+NOTE: File and folder names might have higher version numbers than specifically noted in this document.

doc-content/enterprise-only/employee-rostering/er-deploy-s2i-proc.adoc

@@ -0,0 +1,15 @@
+[id='er-deploy-s2i-proc']
+= Deploying using the Source to Image (S2I) template
+.Procedure
+. Log in to the OpenShift web console and click *Import YAML/JSON* in the upper right part of the browser window.
+. Select the project to add to from the *Add to Project* drop down menu, or select *Create Project* to create a new project. If creating a new project, enter a new project name, display name, and description.
+. Click the *Browse* button and navigate to the `optashift-employee-rostering-template.yaml` file. Starting from the `optashift-employee-rostering-{MAVEN_ARTIFACT_VERSION}` folder, access the file by clicking *sources > openshift > templates*.
+. Click *Create*.
+. In the Add Template dialog box, click *Continue* to accept the default settings.
+. In the Import YAML/JSON dialog box, click *Create* to accept the default settings.
+. In the Success dialog box, click *Close*. Then wait for the build and deployment to complete. This process might take several minutes.
+. When the deployment completes, click the link in the upper right corner above the shaded bar to open the application.
+[NOTE]
+====
+Perform a hard refresh of your browser page if the web app does not open for more than a minute after clicking the link.
+====

doc-content/enterprise-only/employee-rostering/er-deploy-script-proc.adoc

@@ -0,0 +1,42 @@
+[id='er-deploy-script-proc']
+= Deploying the application using the provided script
+
+.Prerequisites
+* You must be logged in to the target OpenShift environment using the `oc` command line tool. For more information about this tool, see https://access.redhat.com/documentation/en-us/openshift_container_platform/3.10/html-single/cli_reference/[CLI Reference].
+. Java Development Kit and Maven must be installed on your local machine. 
+. A `bash` shell environment must be available on your local machine.
+
+.Procedure
+. Using the command line, change to the `optashift-employee-rostering-{MAVEN_ARTIFACT_VERSION}/sources` folder.
+. Run the provision script to build and deploy the application:
++
+[source]
+----
+./provision.sh setup employee-rostering --binary
+----
++
+[NOTE]
+====
+If the current OpenShift user name contains characters that are not letters or numbers, the deployment might fail. You can resolve this issue by providing an additional parameter: `./provision.sh setup employee-rostering --binary --project-suffix optaweb`.  This example uses "optaweb", but you can use any value for the suffix.
+====
++
+Compilation and packaging might take several minutes to complete. They  continually show progress on the command line output.
++
+When the operation is completed, the following message is displayed: `Uploading file "target/ROOT.war" as binary input for the build ...`.
+. Use the OpenShift web UI to view the details for the deployed application. Click the link in the *Routes* section to open the starter application. The first startup can take up to a minute as additional building is completed on the OpenShift platform. 
+[NOTE]
+====
+If the application does not open for more than a minute after clicking the link, perform a hard refresh of your browser page.
+====
+. Optionally, you can use other actions provided by the provision script:
+.. Deploy updates to the code to an existing deployment: 
+[source,bash]
+----
+./provision.sh deploy employee-rostering --binary
+----
++
+.. Remove the application: 
+[source,bash]
+----
+./provision.sh delete employee-rostering
+----

doc-content/enterprise-only/employee-rostering/er-employees-proc.adoc

@@ -0,0 +1,18 @@
+[id='er-employees-proc']
+= Entering the list of employees
+
+You must enter the list of all employees of the business and the skills they possess. The application rosters these employees to spots according to their skills.
+
+.Procedure
+
+. To enter or change the list of employees, click the *Spots* tab.
+. If the list of longer than 10 employees, the numbers of currently visible employees are displayed in the top right part of the browser window, for example, `1-15 of 34`. Use the *<* and *>* buttons to display other employees in the list. 
+. To add a new employee:
+.. Click *Add Employee*.
+.. Enter the name of the employee into the text field under *Employee name*.
+.. Optionally, select one or more skills from the drop-down list under *Skill set*.
+.. Click *Save Employee*.
+. To edit the name and required skills for a spot, click the *Edit Employee* icon (pencil shape) next to the name of the employee.
+. To delete a spot, click the *Delete Employee* icon (trashcan shape) next to the name of the employeeemployee.
+
+NOTE: Within each tenant, employee names must be unique. You cannot delete employees if they are rostered to any shifts.

doc-content/enterprise-only/employee-rostering/er-individualroster-proc.adoc

@@ -0,0 +1,11 @@
+[id='er-individualroster-proc']
+= Viewing employee shifts
+
+You can view the assigned shifts for particular employees in an employee-centric table. The information is the same as the Shift Roster, but the viewing format might be more convenient for informing employees about their assigned shifts.
+
+.Procedure
+. To view a table of employees and shifts, click the *Availability Roster* tab.
+. In the top right part of the browser window, the *Week of* field lists the week for which the roster is displayed. To view other weeks, use the *<* and *>* buttons next to the *Week of* field. Alternatively, click on the date field and change the date to view the week that includes this date.
+. If the list is longer than 10 employees, the numbers of currently visible employees are displayed in the top right part of the browser window, for example, `1-15 of 34`. Use the *<* and *>* buttons next to the numbers to display other employees in the list. 
+
+In the draft period, the borders of boxes representing shifts are dotted lines. In the published periods, the borders are unbroken lines.

doc-content/enterprise-only/employee-rostering/er-openshift-template-proc.adoc

@@ -0,0 +1,10 @@
+[id='er-openshift-template-proc']
+= Deploying the application on OpenShift using the template
+
+You can use the OpenShift template to deploy the Employee Rostering starter application on {OPENSHIFT}. 
+
+.Prerequisite
+
+A MySQL or PostgreSQL database server must be available. This server must either run in the OpenShift infrastructure or be available by network connection from it.
+
+*Additional information required if we are documenting this*

doc-content/enterprise-only/employee-rostering/er-periods-con.adoc

@@ -0,0 +1,12 @@
+[id='er-periods-con']
+= The draft and published periods
+
+At any particular moment, you can use the application to create the roster for a time period called a _draft_ period; by default, the length of a draft period is three weeks. 
+
+When the roster is final for the first week of the draft period, you can _publish_ the roster. At this time, the roster for the first week of the current draft period becomes a _published_ period. Ina published period, the roster is fixed and you can no longer change it automatically (however, emergency manual changes are still possible). This roster can then be distributed to employees so they can plan their time around it. The draft period is shifted a week later.
+
+For example, assume that a draft period of September 1 to September 21 is set. You can automatically create the employee roster for this period. Then, when you publish the roster, the period up to September 7 becomes published. The new draft period is September 8 to September 28.
+
+For instructions about publishing the roster, see <<er-publish-proc>>.
+
+

doc-content/enterprise-only/employee-rostering/er-publish-proc.adoc

@@ -0,0 +1,9 @@
+[id='er-publish-proc']
+= Publishing the shift roster
+
+When you publish the shift roster, the first week of the draft period becomes published. Automatic employee rostering no longer changes any shift assignments in the published period, though emergency manual changing is still possible. The draft period is shifted one week later. For details about draft and published periods, see <<er-periods-con>>.
+
+.Procedure
+. To view and edit the shift roster, click the *Shift Roster* tab.
+. Review the shift roster for the first week of the draft period to ensure that it is acceptable.
+. Click *Publish*.

doc-content/enterprise-only/employee-rostering/er-rotation-con.adoc

@@ -0,0 +1,20 @@
+[id='er-rotation-con']
+= The rotation pattern
+
+The employee rostering application supports a _rotation pattern_ for shifts and employees. 
+
+The rotation pattern is a "model" period of any time starting from two days. The pattern is not tied to a particular date. 
+
+You can set the shift times for every day of the rotation. Optionally, the names of the default employees for each shift in each day can also be set.
+
+NOTE: In the current version, you cannot enter the names of employees in the rotation period. However, you can see the operation of rotation periods with default employees in the example tenants.
+
+When you publish the roster, the application adds a new week to the draft period. At this time, the shifts and, if applicable, default employee names are copied from the rotation pattern to the new part of the draft period.
+
+When the end of the rotation pattern is reached, it is automatically restarted from the beginning.
+
+If weekend shift patterns in your environment are different from weekday shift patterns, use a rotation pattern of one week or a whole number of weeks (for example, 14, 12, or 28 days; the default length is 28 days). Then the pattern is always repeated on the same weekdays and you can set the shifts for different weekdays.
+
+NOTE: In the current version, you have to set every single shift manually. To save time when setting up initial data, use a shorter rotation pattern, for example, 7 days. 
+
+For instructions about editing the rotation pattern, see <<er-rotation-edit-proc>>.

doc-content/enterprise-only/employee-rostering/er-rotation-edit-proc.adoc

@@ -0,0 +1,14 @@
+[id='er-rotation-edit-proc']
+= Viewing and editing the rotation pattern
+
+The rotation pattern contains shifts that are automatically replicated for every period. For details about the rotation pattern, see <<er-rotation-con>>.
+
+You can view the rotation pattern, add, move, and delete shifts.
+
+.Procedure
+. To view and edit the rotation pattern, click the *Rotation* tab. 
+. To view additional days of the rotation pattern, use the horizontal scroll bar at the bottom of the browser window.
+. To add a shift, click an empty area of the table. The application adds a shift, determining the slot and time span automatically from the location of the click.
+. To change the start or end time of a shift, move the mouse pointer to the left or right border of the box representing the shift and drag the border.
+. To delete a shift, hold the *Shift* key on the keyboard and click a shift.
+

doc-content/enterprise-only/employee-rostering/er-shiftroster-proc.adoc

@@ -0,0 +1,22 @@
+[id='er-shiftroster-proc']
+= Viewing and editing shifts in the shift roster
+
+The Shift Roster is a table of all spots and all possible time spans. 
+
+If an employee must be present in a spot during a time span, a _shift_ must exist for this spot and this time span. If a spot requires several employees at the same time, you can create several shifts for the same spot and time span.
+
+Each shift is represented by a rectangle at the intersection of a spot (row) and time span (column).
+
+When new time is added to the draft period, the application copies the shifts (and default employees, if present) from the rotation pattern into this new part of the draft period. You can also manually add and edit shifts in the draft period. 
+
+.Procedure
+. To view and edit the shift roster, click the *Shift Roster* tab.
+. In the top right part of the browser window, the *Week of* field lists the week for which the roster is displayed. To view other weeks, use the *<* and *>* buttons. Alternatively, click on the date field and change the date to view the week that includes this date.
+. To add a shift, click an open area of the schedule. The application adds a shift, determining the slot and time span automatically from the location of the click.
+. To edit a shift, click the shift. You can set the following values for a shift:
+** *From* and *To* date and time: The exact time and duration of the shift.
+** *Employee*: The employee assigned to the shift.
+** *Pinned*: Whether the employee is _pinned_ to the shift. If an employee is pinned, automatic employee rostering cannot change the assignment of the employee to the shift. A pinned employee is not automatically replicated to any other shift.
++
+To save the changes, click *Apply*.
+. To delete a shift, click the shift, and then click *Delete shift*.