27 files changed, 383 insertions, 6 deletions
diff --git a/docs/BPMN_Main_Process_Flows.rst b/docs/BPMN_Main_Process_Flows.rst
new file mode 100644
index 0000000000..abc006e813
--- /dev/null
+++ b/docs/BPMN_Main_Process_Flows.rst
@@ -0,0 +1,40 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+.. Copyright 2017 Huawei Technologies Co., Ltd.
+
+BPMN Main Process Flows
+========================
+
+Characteristics
+----------------
+
+**Invoked by an API Handler**
+
+  The BPMN application (war) exposes a REST endpoint to which the API Handler(s) send requests for flow execution.  The message sent by the API Handler to this endpoint is a JSON wrapper containing:
+  
+    * The original request received by the API handler from the portal or other client.
+    * Metadata such as the request-id generated by the API Handler for the request.
+    * The name of the BPMN process to execute (obtained by the API Handler from the mso_catalog.service_recipe table.
+  
+**Asynchronous Service Model**
+  
+  All main process flows implement an asynchronous service model.  The connection to the API Handler is kept open until the main process flow sends back a response.  In the flow shown below, this is done by the "Send Sync Ack Response" script task.  A flow is expected to send a response after validating the request, but before performing any long running tasks or tasks that could cause the process to be suspended.
+  
+  After the synchronous response is sent, the flow continues to execute.  When the flow ends, it may optionally send an asynchronous notification to a callback URL provided in the original request (behavior depends on the API agreement)
+  
+**Typically calls one or more subprocess flows**
+
+  Main process flows usually implement the high-level service logic, delegating the "real" work to reusable subflows (Building Blocks) or custom subflows
+  
+**Handles "Completion" and "Fallout" tasks**
+
+  "Completion" tasks are those that occur when the process ends successfully, and "Fallout" tasks are those that occur when the process fails.  Activities include:
+  
+    * Updating the mso_requests database.
+    * Rolling back uncompleted work.
+    * Sending an asynchronous callback notification.
+
+Example: CreateVfModuleVolumeInfraV1.bpmn
+------------------------------------------
+
+.. image:: images/BPMN_Main_Process_Flows_1.png
+\ No newline at end of file
diff --git a/docs/BPMN_Project_Structure.rst b/docs/BPMN_Project_Structure.rst
new file mode 100644
index 0000000000..3c5ccc3e7d
--- /dev/null
+++ b/docs/BPMN_Project_Structure.rst
@@ -0,0 +1,47 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+.. Copyright 2017 Huawei Technologies Co., Ltd.
+
+BPMN Project Structure
+=======================
+
+BPMN main process flow
+----------------------
+
+A BPMN main process flow is a top-level flow.  All main process flows are under the src/main/resources/process folder.
+
+CreateVfModuleVolumeInfraV1 is a main process flow.
+
+.. image:: images/bpmn_project_structure_1.png
+
+Open BPMN files with the camunda modeler (standalone application).  To launch the modeler from eclipse, right-click→open-with→Other→Browse.  Select Check the boxes on the dialog so that eclipse will open all .bpmn files with the camunda-modeler executable.
+
+BPMN subprocess flow
+---------------------
+
+A BPMN subprocess flow is meant to be invoked by other flows (either main process flows or other subprocess flows).  All subprocess flows are under the src/main/resources/subprocess folder.
+
+The CreateVfModuleVolumeInfraV1 process flow is delivered with two custom subflows: DoCreateVfModuleVolumeV2 and DoCreateVfModuleVolumeRollback.
+
+.. image:: images/bpmn_project_structure_2.png
+
+Groovy scripts
+---------------
+
+There is one groovy script for each BPMN file.  Groovy scripts are invoked by script tasks within the BPMN flows.
+
+.. image:: images/bpmn_project_structure_3.png
+
+Unit Tests
+-----------
+
+Normally, we create a unit test class for every flow.  This one is missing a unit test for its rollback flow.
+
+.. image:: images/bpmn_project_structure_4.png
+
+Unit Test Resource Files
+------------------------
+
+Any files needed by the unit tests are kept under the src/test/resources/__files folder.
+
+.. image:: images/bpmn_project_structure_5.png
+\ No newline at end of file
diff --git a/docs/Building_SO.rst b/docs/Building_SO.rst
new file mode 100644
index 0000000000..29ff6bd0e8
--- /dev/null
+++ b/docs/Building_SO.rst
@@ -0,0 +1,79 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+.. Copyright 2017 Huawei Technologies Co., Ltd.
+
+Building SO
+============
+
+Build software with unit tests
+------------------------------
+
+.. code-block:: bash
+
+  cd $HOME/onap/workspace/SO/libs
+
+  $HOME/onap/apache-maven-3.3.9/bin/mvn -s $HOME/onap/.m2/settings.xml clean install
+
+  cd $HOME/onap/workspace/SO/so
+
+  $HOME/onap/apache-maven-3.3.9/bin/mvn -s $HOME/onap/.m2/settings.xml clean install
+
+Build software without unit tests
+----------------------------------
+
+.. code-block:: bash
+
+  cd $HOME/onap/workspace/SO/libs
+
+  $HOME/onap/apache-maven-3.3.9/bin/mvn -s $HOME/onap/.m2/settings.xml -DskipTests -Dmaven.test.skip=true clean install
+
+  cd $HOME/onap/workspace/SO/so
+
+  $HOME/onap/apache-maven-3.3.9/bin/mvn -s $HOME/onap/.m2/settings.xml -DskipTests -Dmaven.test.skip=true clean install
+
+Build docker images
+--------------------
+
+SO docker images are built using the "docker" maven profile.  During the build, the chef-repo and so-docker repositories are cloned from gerrit into the "so" directory structure.  Extra definitions are required in the build environment to make this happen.   You may need to adjust the definition of mso.chef.git.url.prefix to match the way you authenticate yourself when performing git clone.
+
+If you are behind a corporate firewall, you can specify proxy definitions for the constructed docker images.
+
+**Remove existing docker containers and images**
+
+.. code-block:: bash
+
+  docker stop $(docker ps -qa)
+
+  docker rm $(docker ps -aq)
+
+  docker rmi -f $(docker images -q)
+
+**Build docker images (without proxy definition):**
+
+.. code-block:: bash
+
+  cd $HOME/onap/workspace/SO/so/packages
+
+  $HOME/onap/apache-maven-3.3.9/bin/mvn -s $HOME/onap/.m2/settings.xml clean install -P docker
+  -Dmso.chef.git.url.prefix=ssh://$USER@gerrit.onap.org:29418 -Dmso.chef.git.branchname=master
+  -Dmso.chef.git.url.suffix.chef.repo=so/chef-repo -Dmso.chef.git.url.suffix.chef.config=so/so-config
+  -Ddocker.buildArg.http_proxy=http://one.proxy.att.com:8080
+  -Ddocker.buildArg.https_proxy=http://one.proxy.att.com:8080
+
+**Build docker images (with proxy definition):**
+
+.. code-block:: bash
+
+  cd $HOME/onap/workspace/SO/so/packages
+  
+  $HOME/onap/apache-maven-3.3.9/bin/mvn -s $HOME/onap/.m2/settings.xml clean install -P docker
+  -Dmso.chef.git.url.prefix=ssh://$USER@gerrit.onap.org:29418 -Dmso.chef.git.branchname=master
+  -Dmso.chef.git.url.suffix.chef.repo=so/chef-repo -Dmso.chef.git.url.suffix.chef.config=so/so-config
+  -Ddocker.buildArg.http_proxy=http://proxyhost:port -Ddocker.buildArg.https_proxy=http://proxyhost:port
+
+Build with Integration Tests
+-----------------------------
+
+This is done exactly as described for building docker images, except that the maven profile to use is "with-integration-tests" instead of "docker".  Integration tests are executed inside docker containers constructed by the build.
+
+
diff --git a/docs/Camunda_Cockpit_Enterprise_Edition.rst b/docs/Camunda_Cockpit_Enterprise_Edition.rst
new file mode 100644
index 0000000000..3e2d15bf15
--- /dev/null
+++ b/docs/Camunda_Cockpit_Enterprise_Edition.rst
@@ -0,0 +1,143 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+.. Copyright 2017 Huawei Technologies Co., Ltd.
+
+Camunda Cockpit Enterprise Edition
+==================================
+
+The Community Edition of Camunda is the version normally built into SO.  With the Community Edition, you can see process definitions, but you cannot inspect running or completed process instances, which is an essential debugging capability.  This capability is available only in the Enterprise Edition and requires a commercial license.  If you have such a license, you can build SO with the Enterprise Edition.  Your use must be consistent with the terms of your license, of course.
+
+With the Enterprise Edition cockpit, you can:
+
+  * See a trace of tasks executed by a running or completed process instance.
+  * Look at execution variables in a running or completed process instance.
+  * Look at called subprocesses in a running or completed process instance.
+
+Maven Repository for Camunda EE Artifacts
+------------------------------------------
+
+To build with Camunda EE, you will need a maven repository containing the Camunda EE artifacts.   This can be a nexus repository or a local repository in your filesystem.
+
+To construct a local repository, start with this structure for the 7.7.3-ee version of Camunda:
+
+  camunda-ee-repository.zip_
+
+.. _camunda-ee-repository.zip: https://wiki.onap.org/download/attachments/16001686/camunda-ee-repository.zip?version=1&modificationDate=1507838888000&api=v2
+
+*NOTE*: the zip archive does not contain the actual Enterprise Edition JAR and WAR files.  It contains zero-length files as placeholders.  You will need to replace the zero-length files with files you obtain from Camunda.  The archive does contain all the poms, checksums, and metadata required to make it a functional maven repository.
+
+Here's the minimum set of artifacts you need to build the SO Amsterdam release software:
+
+  camunda-engine-7.7.3-ee.jar
+
+  camunda-webapp-7.7.3-ee-classes.jar
+
+  camunda-webapp-7.7.3-ee.war
+
+  camunda-webapp-ee-jboss-standalone-7.7.3-ee.war
+
+  camunda-engine-cdi-7.7.3-ee.jar
+
+  camunda-engine-rest-7.7.3-ee-classes.jar
+
+  camunda-engine-plugin-spin-7.7.3-ee.jar
+
+  camunda-engine-plugin-connect-7.7.3-ee.jar
+
+  camunda-engine-rest-core-7.7.3-ee.jar
+
+  camunda-engine-feel-api-7.7.3-ee.jar
+
+  camunda-engine-feel-juel-7.7.3-ee.jar
+
+  camunda-engine-dmn-7.7.3-ee.jar
+
+  camunda-engine-spring-7.7.3-ee.jar
+
+  camunda-bpmn-model-7.7.3-ee.jar
+
+  camunda-xml-model-7.7.3-ee.jar
+
+  camunda-dmn-model-7.7.3-ee.jar
+
+  camunda-cmmn-model-7.7.3-ee.jar
+
+Maven settings.xml
+------------------
+
+Add a profile to your maven settings.xml to include the repository containing your Camunda EE artifacts.
+
+For example:
+
+.. code-block:: bash
+
+  <profile>
+  <!-- profile for artifacts not in public repositories -->
+  <id>my-local-artifacts</id>
+  <repositories>
+    <repository>
+      <!-- Local repository for Camunda Enterprise Edition -->
+      <!-- YOU MUST HAVE A VALID LICENSE TO USE THIS -->
+      <id>camunda-ee</id>
+      <name>camunda-ee</name>
+      <url>file:///home/john/onap/camunda-ee-repository</url>
+    </repository>
+  </repositories>
+  </profile>
+
+And add your profile to the list of active profiles:
+
+.. code-block:: bash
+
+  <activeProfiles>
+
+  <activeProfile>my-local-artifacts</activeProfile>
+
+  <activeProfile>openecomp-staging</activeProfile>
+
+  <activeProfile>openecomp-public</activeProfile>
+
+  <activeProfile>openecomp-release</activeProfile>
+
+  <activeProfile>openecomp-snapshots</activeProfile>
+
+  <activeProfile>opendaylight-release</activeProfile>
+
+  <activeProfile>opendaylight-snapshots</activeProfile>
+
+  </activeProfiles>
+
+Building
+--------
+
+Add these options to the mvn command line when you build "so"
+
+.. code-block:: bash
+
+  -Dcamunda.version=7.7.3-ee -Dcamunda.bpm.webapp.artifact=camunda-webapp-ee-jboss-standalone
+
+Installation
+-------------
+
+The cockpit is part of the SO image.  There are no special installation requirements.  When you log in, you will need to enter your license information.  Alternatively, you can insert your license directly into the camundabpmn database before you log in:
+
+.. code-block:: bash
+
+  INSERT INTO camundabpmn.ACT_GE_PROPERTY VALUES ('camunda-license-key','YOUR-LICENCE-KEY-HERE',1);
+
+Logging In
+-----------
+
+Because port 8080 on the docker host machine is forwarded to port 8080 in the SO docker container you can log into the Enterprise Edition cockpit by browsing to this URL:
+
+  http://*dockerhost*:8080/camunda
+
+  Where dockerhost is the docker host system.
+
+If you can use a browser on the docker host system, then use a localhost address:
+
+  http://localhost:8080/camunda
+
+The user is "admin" and the password is the same as the jboss admin password, which is not displayed here.
+
+.. image:: images/Camunda_Cockpit_Enterprise_1.png
diff --git a/docs/Install_Configure_SO.rst b/docs/Install_Configure_SO.rst
index 5771a10e84..a1a9bf4317 100644
--- a/docs/Install_Configure_SO.rst
+++ b/docs/Install_Configure_SO.rst
@@ -18,79 +18,147 @@ Make sure you have the VirtualBox Guest Additions ISO for your version of Virtua
 Create a new VM in VirtualBox for Ubuntu
 ----------------------------------------
 Type: Linux
+
 Version: Ubuntu (64-bit)
+
 At least 2048 MB memory
+
 At least 40 GB VDI
+
 Network: Attached to: NAT
 
 Create a port-forwarding rule for SSH
 -------------------------------------
 Create a port-forwarding rule so that you can use PuTTY (or other SSH client) to connect to the VM.
+
 Go to "Network" settings in VirtualBox, add a port forwarding rule:
+
 Name: SSH
+
 Protocol: TCP
+
 Host IP: 127.0.0.1
+
 Host Port: 1022
+
 Guest IP: <leave blank>
+
 Guest Port: 22
 
+.. image:: images/Configure_ubuntu_SO_1.png
+
+.
+
+.. image:: images/Configure_ubuntu_SO_2.png
+
 Create Shared Folder
 --------------------
 This is oriented to Windows users.  If you're using a MAC or a Linux host computer, the details may be different.  You can share any folder on the host computer with the Ubuntu VM.  On Windows, a practical choice is to share the C:\Users folder, so that your Windows home directory will be accessible from the Ubuntu VM.
+
 Go to "Shared Folders" settings in VirtualBox, add a share:
+
 Folder Path: C:\Users
+
 Folder Name: Users
+
 Auto-mount: <checked>
+
 Read-only: <unchecked>
 
+.. image:: images/Configure_ubuntu_SO_3.png
+
+.
+
+.. image:: images/Configure_ubuntu_SO_4.png
+
 Install Ubuntu in the VM
 ------------------------
 On the "Storage" panel in VirtualBox, click on "[ optical drive ]" and then "Choose Disk Image".  Select your Ubuntu ISO image.
 
+.. image:: images/Configure_ubuntu_SO_5.png
+
 After selecting the ISO image, start the VM.
+
 Follow the prompts to install Ubuntu.
 
 Proxy Configuration (optional)
 ------------------------------
 If you're behind a corporate firewall, configure some proxy settings.  NOTE: your proxy configuration may require username and password credentials, not shown here.
 **Ubuntu system proxy setting:**
+
 	System Settings → Network → Network proxy
+	
 	(Replace "proxyhost" and port with your actual proxy information)
 
+.. image:: images/Configure_ubuntu_SO_6.png
+	
 **apt proxy setting:**
 	Edit /etc/apt/apt.conf and add one line at the top (replace "proxyhost:port" with your actual proxy information):
+	
 		Acquire::http::Proxy "http://proxyhost:port";
+		
 	Reboot the VM.
 	
 Install SSH Server
 ------------------
-sudo apt update
-sudo apt install openssh-server
+
+.. code-block:: bash
+
+    sudo apt update
+    sudo apt install openssh-server
 
 Connect to the VM from your host computer
 -----------------------------------------
 	The PuTTY SSH client is popular.  A connection to localhost:1022 (or whatever port you have forwarded) will go to the VM.
 
+.. image:: images/Configure_ubuntu_SO_7.png
+	
 Install VirtualBox Guest Additions
 ----------------------------------
 On the "Storage" panel in VirtualBox, click on "[ optical drive ]" and then "Choose Disk Image".  Select your VirtualBox Guest Additions ISO image.
 
+.. image:: images/Configure_ubuntu_SO_8.png
+
 In a VM terminal window, mount the cdrom:
+
+.. code-block:: bash
+
 	sudo mkdir -p /media/cdrom
 	sudo mount /dev/cdrom /media/cdrom
+	
 Install necessary dependencies:
-	sudo apt update
-	sudo apt install gcc g++ dkms
+
+.. code-block:: bash
+
+    sudo apt update
+    sudo apt install gcc g++ dkms
+	
 Install the guest additions.  NOTE: look for errors in the command output!  If you see an error that says you are missing kernel headers, the most likely cause is that you are using a VirtualBox version that is too old.  The error message is misleading.
+
+.. code-block:: bash
+
 	cd /media/cdrom
 	sudo ./VBoxLinuxAdditions.run
 
+.. image:: images/Configure_ubuntu_SO_9.png	
+	
 Add yourself to the vboxsf user group (replace "userid" with your user ID):
+	
+.. code-block:: bash	
+	
 	sudo usermod -a -G vboxsf userid
+	
 Reboot the VM.
+
 In a VM terminal window, verify that you can access your home directory on the host computer, which should be mounted under here:
 	/media/sf_Users
 	
 Further Reading
 ----------------------------------------	
-https://wiki.onap.org/display/DW/Development+Environment
-\ No newline at end of file
+
+.. toctree::
+   :maxdepth: 1
+
+   Install_Docker.rst
+   Configure_git_and_gerrit.rst
+   Workspace_and_Development_Tools.rst
+\ No newline at end of file
diff --git a/docs/UUI-SO API Specification v0.1(1).docx b/docs/UUI-SO API Specification v0.1(1).docx
deleted file mode 100644
index a6dfbd0b1a..0000000000
--- a/docs/UUI-SO API Specification v0.1(1).docx
+++ /dev/null
diff --git a/docs/architecture.rst b/docs/architecture.rst
index c9f6838216..67cf67f745 100644
--- a/docs/architecture.rst
+++ b/docs/architecture.rst
@@ -2,7 +2,7 @@
 .. http://creativecommons.org/licenses/by/4.0
 .. Copyright 2017 Huawei Technologies Co., Ltd.
 
-Service Orchestrator
+ONAP Service Orchestration - Architecture
 ========================================================
 
 SO Architecture
diff --git a/docs/images/BPMN_Main_Process_Flows_1.png b/docs/images/BPMN_Main_Process_Flows_1.png
new file mode 100644
index 0000000000..57337d621f
--- /dev/null
+++ b/docs/images/BPMN_Main_Process_Flows_1.png
diff --git a/docs/images/BPMN_Subprocess_process_flows_1.png b/docs/images/BPMN_Subprocess_process_flows_1.png
new file mode 100644
index 0000000000..5ec7e7ce9c
--- /dev/null
+++ b/docs/images/BPMN_Subprocess_process_flows_1.png
diff --git a/docs/images/Camunda_Cockpit_1.png b/docs/images/Camunda_Cockpit_1.png
new file mode 100644
index 0000000000..cdcc6f3b8e
--- /dev/null
+++ b/docs/images/Camunda_Cockpit_1.png
diff --git a/docs/images/Camunda_Cockpit_2.png b/docs/images/Camunda_Cockpit_2.png
new file mode 100644
index 0000000000..a696a68cb0
--- /dev/null
+++ b/docs/images/Camunda_Cockpit_2.png
diff --git a/docs/images/Camunda_Cockpit_3.png b/docs/images/Camunda_Cockpit_3.png
new file mode 100644
index 0000000000..a298fe0669
--- /dev/null
+++ b/docs/images/Camunda_Cockpit_3.png
diff --git a/docs/images/Camunda_Cockpit_4.png b/docs/images/Camunda_Cockpit_4.png
new file mode 100644
index 0000000000..ff445f364d
--- /dev/null
+++ b/docs/images/Camunda_Cockpit_4.png
diff --git a/docs/images/Configure_ubuntu_SO_1.png b/docs/images/Configure_ubuntu_SO_1.png
new file mode 100644
index 0000000000..a5a8301628
--- /dev/null
+++ b/docs/images/Configure_ubuntu_SO_1.png
diff --git a/docs/images/Configure_ubuntu_SO_2.png b/docs/images/Configure_ubuntu_SO_2.png
new file mode 100644
index 0000000000..d3b215f76f
--- /dev/null
+++ b/docs/images/Configure_ubuntu_SO_2.png
diff --git a/docs/images/Configure_ubuntu_SO_3.png b/docs/images/Configure_ubuntu_SO_3.png
new file mode 100644
index 0000000000..ef4f21bbf4
--- /dev/null
+++ b/docs/images/Configure_ubuntu_SO_3.png
diff --git a/docs/images/Configure_ubuntu_SO_4.png b/docs/images/Configure_ubuntu_SO_4.png
new file mode 100644
index 0000000000..f857eff017
--- /dev/null
+++ b/docs/images/Configure_ubuntu_SO_4.png
diff --git a/docs/images/Configure_ubuntu_SO_5.png b/docs/images/Configure_ubuntu_SO_5.png
new file mode 100644
index 0000000000..01d2016752
--- /dev/null
+++ b/docs/images/Configure_ubuntu_SO_5.png
diff --git a/docs/images/Configure_ubuntu_SO_6.png b/docs/images/Configure_ubuntu_SO_6.png
new file mode 100644
index 0000000000..17b9986d90
--- /dev/null
+++ b/docs/images/Configure_ubuntu_SO_6.png
diff --git a/docs/images/Configure_ubuntu_SO_7.png b/docs/images/Configure_ubuntu_SO_7.png
new file mode 100644
index 0000000000..d233847306
--- /dev/null
+++ b/docs/images/Configure_ubuntu_SO_7.png
diff --git a/docs/images/Configure_ubuntu_SO_8.png b/docs/images/Configure_ubuntu_SO_8.png
new file mode 100644
index 0000000000..01d2016752
--- /dev/null
+++ b/docs/images/Configure_ubuntu_SO_8.png
diff --git a/docs/images/Configure_ubuntu_SO_9.png b/docs/images/Configure_ubuntu_SO_9.png
new file mode 100644
index 0000000000..2cc96b379f
--- /dev/null
+++ b/docs/images/Configure_ubuntu_SO_9.png
diff --git a/docs/images/Docker_install_1.png b/docs/images/Docker_install_1.png
new file mode 100644
index 0000000000..1e9c177ee5
--- /dev/null
+++ b/docs/images/Docker_install_1.png
diff --git a/docs/images/Workspace_and_Development_Tools.png b/docs/images/Workspace_and_Development_Tools.png
new file mode 100644
index 0000000000..46f8fe4baf
--- /dev/null
+++ b/docs/images/Workspace_and_Development_Tools.png
diff --git a/docs/images/Workspace_and_Development_Tools_2.png b/docs/images/Workspace_and_Development_Tools_2.png
new file mode 100644
index 0000000000..1f3fff0776
--- /dev/null
+++ b/docs/images/Workspace_and_Development_Tools_2.png
diff --git a/docs/images/Workspace_and_Development_Tools_3.png b/docs/images/Workspace_and_Development_Tools_3.png
new file mode 100644
index 0000000000..3d2f35df82
--- /dev/null
+++ b/docs/images/Workspace_and_Development_Tools_3.png
diff --git a/docs/images/Workspace_and_Development_Tools_4.png b/docs/images/Workspace_and_Development_Tools_4.png
new file mode 100644
index 0000000000..31a424e4d2
--- /dev/null
+++ b/docs/images/Workspace_and_Development_Tools_4.png