Issue-ID: DOC-500

remove "service Deployment" that was not explaining anything
add "service instantiation" section with a lot of useful informations
ammend after review
amend about NBI that is able to handle 2 instantiations methods

Signed-off-by: Rene_Robert <rene.robert@orange.com>
Change-Id: I4e3bf8830a44f84acb11d0c0afb3ce3012227252

9 files changed, 1060 insertions, 0 deletions

diff --git a/docs/guides/onap-user/instantiate/index.rst b/docs/guides/onap-user/instantiate/index.rst
new file mode 100644
index 000000000..b45790342
--- /dev/null
+++ b/docs/guides/onap-user/instantiate/index.rst
@@ -0,0 +1,32 @@
+.. This work is licensed under a Creative Commons Attribution 4.0
+.. International License.  http://creativecommons.org/licenses/by/4.0
+.. Copyright 2017 AT&T Intellectual Property.  All rights reserved.
+
+.. _user-guides:
+
+Instantiate
+===========
+The following guides are provided to describe tasks that a user of
+ONAP may need to perform when instantiating a service.
+
+Instantiation includes the following topics:
+
+.. toctree::
+   :maxdepth: 2
+
+   Pre-instantiation operations <./pre_instantiation/index.rst>
+
+   Instantiation operation(s) <./instantiation/index.rst>
+
+
+**e2eServiceInstance** method is a hard-coded approach with dedicated/specific
+service BPMN workflow. That means it is linked to ONAP source code
+and lifecycle.
+
+**Alacarte** method required the Operator actor to build and send
+a lot of operations. To build those requests, Operator actor needs to
+define/collect by himself all VNF parameters/values.
+
+**Macro** method required the Operator actor to build and send only one request and,
+thanks to CDS Blueprint templates, ONAP will collect and assign
+by itself all paramters/values.
diff --git a/docs/guides/onap-user/instantiate/instantiation/index.rst b/docs/guides/onap-user/instantiate/instantiation/index.rst
new file mode 100644
index 000000000..dcbe153da
--- /dev/null
+++ b/docs/guides/onap-user/instantiate/instantiation/index.rst
@@ -0,0 +1,28 @@
+.. This work is licensed under a Creative Commons Attribution 4.0
+.. International License. http://creativecommons.org/licenses/by/4.0
+.. Copyright 2019 ONAP Contributors.  All rights reserved.
+
+.. _doc_guide_user_ser_inst:
+
+
+Service Instantiation methods
+=============================
+
+
+Declare PNF instances:
+
+.. toctree::
+   :maxdepth: 2
+
+   Declare PNF instances <./pnf_instance/index.rst>
+
+Instantiate a Service:
+
+.. toctree::
+   :maxdepth: 2
+
+   using ONAP VID Portal with "A La Carte" method<./vid/index.rst>
+   using ONAP UUI Portal with "e2eServiceInstance" method<./uui/index.rst>
+   using ONAP NBI REST API (TM Forum) with "A La Carte" method <./nbi/index.rst>
+   using ONAP SO REST API with "A La Carte" method <./so1/index.rst>
+   using ONAP SO REST API with "Macro" mode method <./so2/index.rst>
diff --git a/docs/guides/onap-user/instantiate/instantiation/nbi/index.rst b/docs/guides/onap-user/instantiate/instantiation/nbi/index.rst
new file mode 100644
index 000000000..696232517
--- /dev/null
+++ b/docs/guides/onap-user/instantiate/instantiation/nbi/index.rst
@@ -0,0 +1,88 @@
+.. This work is licensed under a Creative Commons Attribution 4.0
+.. International License. http://creativecommons.org/licenses/by/4.0
+.. Copyright 2019 ONAP Contributors.  All rights reserved.
+
+.. _doc_guide_user_ser_inst:
+
+
+Alacarte mode Service Instantiation via ONAP NBI API (TM Forum)
+===============================================================
+
+ONAP NBI allow you to use a TM Forum standardized API (serviceOrder API)
+
+ONAP NBI will convert that request to ONAP SO request.
+
+
+ServiceOrder management in NBI will support 2 modes:
+
+* E2E integration - NBI calls SO API to perform an End-To-end integration
+* Service-level only integration - NBI will trigger only SO request at
+  serviceInstance level (not at VNF, not at Vf-module level and nothing will
+  be created on cloud platform)
+
+ONAP SO prerequisite: SO must be able to find a BPMN to process service
+fulfillment (integrate VNF, VNF activation in SDNC, VF module
+
+The choice of the mode is done by NBI depending on information retrieved
+in SDC. If the serviceSpecification is within a Category “E2E Service” ,
+NBI will use E2E SO API, if not only API at service instance level
+will be used.
+
+There is no difference or specific expectation in the service order API
+used by NBI user.
+
+
+Example of serviceOrder to instantiate (=add) a service based on model
+with id=0d463b0c-e559-4def-8d7b-df64cfbd3159
+
+
+::
+
+  curl -X POST \
+    http://nbi.api.simpledemo.onap.org:30274/nbi/api/v4/serviceOrder \
+    -H 'Accept: application/json' \
+    -H 'Content-Type: application/json' \
+    -H 'cache-control: no-cache' \
+    -d '{
+    "externalId": "BSS_order_001",
+    "priority": "1",
+    "description": "this is a service order to instantiate a service",
+    "category": "Consumer",
+    "requestedStartDate": "",
+    "requestedCompletionDate": "",
+    "relatedParty": [
+      {
+        "id": "JohnDoe",
+        "role": "ONAPcustomer",
+        "name": "JohnDoe"
+      }
+    ],
+    "orderItem": [
+      {
+        "id": "1",
+        "action": "add",
+        "service": {
+          "name": "my_service_model_instance_01",
+          "serviceState": "active",
+          "serviceSpecification": {
+            "id": "0d463b0c-e559-4def-8d7b-df64cfbd3159"
+          }
+        }
+      }
+    ]
+  }'
+
+In the response, you will obtain the serviceOrderId value.
+
+Then you have the possibility to check about the serviceorder
+(here after the serviceOrderId=5d06309da0e46400017b1123).
+
+This will allow you to get the serviceOrder Status (completed, failed...)
+
+::
+
+  curl -X GET \
+    http://nbi.api.simpledemo.onap.org:30274/nbi/api/v4/serviceOrder/5d06309da0e46400017b1123 \
+    -H 'Accept: application/json' \
+    -H 'Content-Type: application/json' \
+    -H 'cache-control: no-cache'
diff --git a/docs/guides/onap-user/instantiate/instantiation/pnf_instance/index.rst b/docs/guides/onap-user/instantiate/instantiation/pnf_instance/index.rst
new file mode 100644
index 000000000..7fbfdbe79
--- /dev/null
+++ b/docs/guides/onap-user/instantiate/instantiation/pnf_instance/index.rst
@@ -0,0 +1,107 @@
+.. This work is licensed under a Creative Commons Attribution 4.0
+.. International License. http://creativecommons.org/licenses/by/4.0
+.. Copyright 2019 ONAP Contributors. All rights reserved.
+
+
+
+Declare PNF instances in ONAP
+=============================
+
+PNF instances can be declared in ONAP inventory (AAI) using REST API
+
+
+An example:
+
+::
+
+  curl -X PUT \
+    https://{{ONAP_LB_IP@}}:30233/aai/v16/network/pnfs/pnf/my_pnf_instance_001 \
+    -H 'Accept: application/json' \
+    -H 'Authorization: Basic QUFJOkFBSQ==' \
+    -H 'Cache-Control: no-cache' \
+    -H 'Content-Type: application/json' \
+    -H 'Postman-Token: f5e2aae0-dc1c-4edb-b9e9-a93b05aee5e8' \
+    -H 'X-FromAppId: AAI' \
+    -H 'X-TransactionId: 999' \
+    -H 'depth: all' \
+    -d '{
+    "pnf-name":" my_pnf_instance_001",
+    "equip-type":" router",
+    "nf-role":"primary",
+    "p-interfaces": {
+        "p-interface": [
+            {
+                "interface-name": "ae1",
+                "port-description": "Link aggregate for trunk between switches"
+            },
+            {
+                "interface-name": "xe-0/0/6",
+                "port-description": "to PNF_instance_002 trunk1"
+            },
+            {
+                "interface-name": "xe-0/0/2",
+                "port-description": "to PNF_instance_003 trunk1"
+            },
+            {
+                "interface-name": "xe-0/0/10",
+                "port-description": "to PNF_instance_004 trunk1"
+            },
+            {
+                "interface-name": "xe-0/0/0",
+                "port-description": "firewall trunk"
+            },
+            {
+                "interface-name": "xe-0/0/14",
+                "port-description": "to PNF_instance_005 trunk1"
+            }
+        ]
+    }
+  }' -k
+
+
+It is possible to declare the location where is deployed the PNF
+(called a "complex" in ONAP AAI)
+
+::
+
+  curl -X PUT \
+    https:// {{ONAP_LB_IP@}}:30233/aai/v11/cloud-infrastructure/complexes/complex/my_complex_name \
+    -H 'Accept: application/json' \
+    -H 'Authorization: Basic QUFJOkFBSQ==' \
+    -H 'Cache-Control: no-cache' \
+    -H 'Content-Type: application/json' \
+    -H 'Postman-Token: 43523984-db01-449a-8a58-8888871110bc' \
+    -H 'X-FromAppId: AAI' \
+    -H 'X-TransactionId: 999' \
+    -H 'depth: all' \
+    -d '{
+    "physical-location-type":"PoP",
+    "physical-location-id":"my_complex_name",
+    "complex-name":"Name of my Complex",
+    "city":"LANNION",
+    "postal-code":"22300",
+    "country":"FRANCE",
+    "street1":"Avenue Pierre Marzin",
+    "region":"Europe"
+  }' -k
+
+
+
+To indicate that a PNF instance is located in a complex, we create a relation
+
+::
+
+  curl -X PUT \
+    https:// {{ONAP_LB_IP@}}:30233/aai/v14/network/pnfs/pnf/my_pnf_instance_001/relationship-list/relationship \
+    -H 'Accept: application/json' \
+    -H 'Authorization: Basic QUFJOkFBSQ==' \
+    -H 'Cache-Control: no-cache' \
+    -H 'Content-Type: application/json' \
+    -H 'Postman-Token: 15315304-17c5-4e64-aada-bb149f1af915' \
+    -H 'X-FromAppId: AAI' \
+    -H 'X-TransactionId: 999' \
+    -H 'depth: all' \
+    -d '{
+      "related-to": "complex",
+      "related-link": "/aai/v11/cloud-infrastructure/complexes/complex/my_complex_name"
+  }' -k
diff --git a/docs/guides/onap-user/instantiate/instantiation/so1/index.rst b/docs/guides/onap-user/instantiate/instantiation/so1/index.rst
new file mode 100644
index 000000000..860f50295
--- /dev/null
+++ b/docs/guides/onap-user/instantiate/instantiation/so1/index.rst
@@ -0,0 +1,366 @@
+.. This work is licensed under a Creative Commons Attribution 4.0
+.. International License. http://creativecommons.org/licenses/by/4.0
+.. Copyright 2019 ONAP Contributors.  All rights reserved.
+
+.. _doc_guide_user_ser_inst:
+
+
+AlaCarte mode Service Instantiation via ONAP SO API
+===================================================
+
+Using ONAP SO API in "Alacarte" mode, you need to send several requests,
+depending on the service model composition.
+
+For example, if your service model is composed of 2 VNF and a Network,
+you will have to build and send :
+
+* a request to SO to create the "service instance" object
+* a request to SO to create the VNF 1 instance object
+* a request to SDNC to declare VNF 1 instance parameters and values
+  (SDNC preload)
+* a request to SO to create the Vf-module 1 instance object
+* a request to SO to create the VNF 2 instance object
+* a request to SDNC to declare VNF 2 instance parameters and values
+  (SDNC preload)
+* a request to SO to create the Vf-module 2 instance object
+* a request to SO to create the Network instance object
+
+
+
+Example to request a service instance directly to ONAP SO
+
+
+TO BE COMPLETED
+
+
+
+In the response, you will obtain the serviceOrderId value.
+
+Then you have the possibility to check about the SO request
+(here after the requestId=e3ad8df6-ea0d-4384-be95-bcb7dd39bbde).
+
+This will allow you to get the serviceOrder Status (completed, failed...)
+
+::
+
+  curl -X GET \
+    http://so.api.simpledemo.onap.org:30277/onap/so/infra/orchestrationRequests/v6/e3ad8df6-ea0d-4384-be95-bcb7dd39bbde \
+    -H 'Accept: application/json' \
+    -H 'Authorization: Basic SW5mcmFQb3J0YWxDbGllbnQ6cGFzc3dvcmQxJA==' \
+    -H 'Content-Type: application/json' \
+    -H 'X-FromAppId: AAI' \
+    -H 'X-TransactionId: get_aai_subscr' \
+    -H 'cache-control: no-cache'
+
+
+To instantiate a VNF, you need to build a complex request.
+All necessary parameters are available in the Tosca service template
+generated by SDC when you defined your service model.
+
+::
+
+  curl -X POST \
+  http://so.api.simpledemo.onap.org:30277/onap/so/infra/serviceInstances/v6/95762b50-0244-4723-8fde-35f911db9263/vnfs \
+  -H 'Accept: application/json' \
+  -H 'Authorization: Basic SW5mcmFQb3J0YWxDbGllbnQ6cGFzc3dvcmQxJA==' \
+  -H 'Content-Type: application/json' \
+  -H 'X-FromAppId: AAI' \
+  -H 'X-TransactionId: get_aai_subscr' \
+  -H 'cache-control: no-cache' \
+  -d '{
+  "requestDetails": {
+    "requestInfo": {
+      "productFamilyId": "0d463b0c-e559-4def-8d7b-df64cfbd3159",
+      "instanceName": "my_service_vnf_instance_001",
+      "source": "VID",
+      "suppressRollback": false,
+      "requestorId": "test"
+    },
+  "modelInfo": {
+    "modelType": "vnf",
+    "modelInvariantId": "4e66bb92-c597-439e-822d-75aaa69b13d4",
+      "modelVersionId": "3b6ba59c-287c-449e-a1da-2db49984a087",
+      "modelName": "my_service_VF",
+      "modelVersion": "1.0",
+      "modelCustomizationId": "",
+      "modelCustomizationName": ""
+    },
+    "requestParameters": {
+      "userParams": [],
+      "aLaCarte": true,
+    "testApi": "VNF_API"
+    },
+    "cloudConfiguration": {
+      "lcpCloudRegionId": "my_cloud_site",
+      "tenantId": "5906b9b8fd9642df9ba1c9e290063439"
+    },
+    "lineOfBusiness": {
+      "lineOfBusinessName": "test_LOB"
+    },
+    "platform": {
+      "platformName": "test_platform"
+    },
+    "relatedInstanceList": [{
+      "relatedInstance": {
+        "instanceId": "95762b50-0244-4723-8fde-35f911db9263",
+        "modelInfo": {
+          "modelType": "service",
+          "modelName": "my-service-model",
+          "modelInvariantId": "11265d8c-2cc2-40e5-95d8-57cad81c18da",
+          "modelVersion": "1.0",
+          "modelVersionId": "0d463b0c-e559-4def-8d7b-df64cfbd3159"
+        }
+      }
+    }]
+  }
+  }'
+
+To instantiate a VF module, you need to build two complex requests
+All necessary parameters are available in the Tosca service template
+generated by SDC when you defined your service model.
+
+1st request is called a "SDNC-preload" for a VNF object and is used
+to store in SDNC some VNF parameters values
+that will be used when instantiating
+
+::
+
+  curl -X POST \
+  http://sdnc.api.simpledemo.onap.org:30202/restconf/operations/VNF-API:preload-vnf-topology-operation \
+  -H 'Accept: application/json' \
+  -H 'Authorization: Basic YWRtaW46S3A4Yko0U1hzek0wV1hsaGFrM2VIbGNzZTJnQXc4NHZhb0dHbUp2VXkyVQ==' \
+  -H 'Content-Type: application/json' \
+  -H 'X-FromAppId: API client' \
+  -H 'X-TransactionId: 0a3f6713-ba96-4971-a6f8-c2da85a3176e' \
+  -H 'cache-control: no-cache' \
+  -d '{
+    "input": {
+        "request-information": {
+            "notification-url": "onap.org",
+            "order-number": "1",
+            "order-version": "1",
+            "request-action": "PreloadVNFRequest",
+            "request-id": "test"
+        },
+        "sdnc-request-header": {
+            "svc-action": "reserve",
+            "svc-notification-url": "http:\/\/onap.org:8080\/adapters\/rest\/SDNCNotify",
+            "svc-request-id": "test"
+        },
+        "vnf-topology-information": {
+            "vnf-assignments": {
+                "availability-zones": [],
+                "vnf-networks": [],
+                "vnf-vms": []
+            },
+            "vnf-parameters": [],
+            "vnf-topology-identifier": {
+                "generic-vnf-name": "my_service_vnf_instance_001",
+                "generic-vnf-type": "",
+                "service-type": "95762b50-0244-4723-8fde-35f911db9263",
+                "vnf-name": "my_service_vfmodule_001",
+                "vnf-type": ""
+            }
+        }
+    }
+  }'
+
+The 2nd request id to instantiate the VF module via ONAP SO
+(instance name must be identical in both requests)
+
+::
+
+  curl -X POST \
+  http://so.api.simpledemo.onap.org:30277/onap/so/infra/serviceInstances/v6/95762b50-0244-4723-8fde-35f911db9263/vnfs//vfModules \
+  -H 'Accept: application/json' \
+  -H 'Authorization: Basic SW5mcmFQb3J0YWxDbGllbnQ6cGFzc3dvcmQxJA==' \
+  -H 'Content-Type: application/json' \
+  -H 'X-FromAppId: AAI' \
+  -H 'X-TransactionId: get_aai_subscr' \
+  -H 'cache-control: no-cache' \
+  -d '{
+  "requestDetails": {
+    "requestInfo": {
+      "instanceName": "my_vfmodule_001",
+      "source": "VID",
+      "suppressRollback": false,
+      "requestorId": "test"
+    },
+  "modelInfo": {
+    "modelType": "vfModule",
+    "modelInvariantId": "",
+    "modelVersionId": "",
+    "modelName": "",
+    "modelVersion": "1",
+    "modelCustomizationId": "",
+    "modelCustomizationName": ""
+  },
+  "requestParameters": {
+    "userParams": [],
+    "testApi": "VNF_API",
+    "usePreload": true
+  },
+    "cloudConfiguration": {
+      "lcpCloudRegionId": "my_cloud_site",
+      "tenantId": "5906b9b8fd9642df9ba1c9e290063439"
+    },
+    "relatedInstanceList": [{
+      "relatedInstance": {
+        "instanceId": "95762b50-0244-4723-8fde-35f911db9263",
+        "modelInfo": {
+          "modelType": "service",
+          "modelName": "my-service-model",
+          "modelInvariantId": "11265d8c-2cc2-40e5-95d8-57cad81c18da",
+          "modelVersion": "1.0",
+          "modelVersionId": "0d463b0c-e559-4def-8d7b-df64cfbd3159"
+        }
+      }
+    },
+    {
+      "relatedInstance": {
+        "instanceId": "",
+        "modelInfo": {
+          "modelType": "vnf",
+          "modelName": "my_service_model_VF",
+          "modelInvariantId": "4e66bb92-c597-439e-822d-75aaa69b13d4",
+          "modelVersion": "1.0",
+          "modelVersionId": "3b6ba59c-287c-449e-a1da-2db49984a087",
+          "modelCustomizationId": "",
+          "modelCustomizationName": ""
+        }
+      }
+    }]
+  }
+  }'
+
+
+
+To instantiate a Neutron Network, you need to build two complex request.
+All necessary parameters are available in the Tosca service template
+generated by SDC when you defined your service model.
+
+
+1st request is the "SDNC-preload" for a network object:
+
+::
+
+  curl -X POST \
+  http://sdnc.api.simpledemo.onap.org:30202/restconf/operations/VNF-API:preload-network-topology-operation \
+  -H 'Accept: application/json' \
+  -H 'Authorization: Basic YWRtaW46S3A4Yko0U1hzek0wV1hsaGFrM2VIbGNzZTJnQXc4NHZhb0dHbUp2VXkyVQ==' \
+  -H 'Content-Type: application/json' \
+  -H 'X-FromAppId: API client' \
+  -H 'X-TransactionId: 0a3f6713-ba96-4971-a6f8-c2da85a3176e' \
+  -H 'cache-control: no-cache' \
+  -d '{
+  "input": {
+    "request-information": {
+      "request-id": "postman001",
+      "notification-url": "http://so.onap.org",
+      "order-number": "postman001",
+      "request-sub-action": "SUPP",
+      "request-action": "PreloadNetworkRequest",
+      "source": "postman",
+      "order-version": "1.0"
+    },
+    "network-topology-information": {
+      "network-policy": [],
+      "route-table-reference": [],
+      "vpn-bindings": [],
+      "network-topology-identifier": {
+        "network-role": "integration_test_net",
+        "network-technology": "neutron",
+        "service-type": "my-service-2",
+        "network-name": "my_network_01",
+        "network-type": "Generic NeutronNet"
+      },
+      "provider-network-information": {
+        "is-external-network": "false",
+        "is-provider-network": "false",
+        "is-shared-network": "false"
+      },
+      "subnets": [
+        {
+      "subnet-name": "my_subnet_01",
+      "subnet-role": "OAM",
+          "start-address": "192.168.90.0",
+          "cidr-mask": "24",
+          "ip-version": "4",
+          "dhcp-enabled": "Y",
+      "dhcp-start-address": "",
+      "dhcp-end-address": "",
+          "gateway-address": "192.168.90.1",
+      "host-routes":[]
+        }
+              ]
+    },
+    "sdnc-request-header": {
+      "svc-action": "reserve",
+      "svc-notification-url": "http://so.onap.org",
+      "svc-request-id": "postman001"
+    }
+  }
+  }'
+
+
+2nd request is to instantiate the network via ONAP SO
+(instance name must be identical in both requests)
+
+
+::
+
+curl -X POST \
+  http://so.api.simpledemo.onap.org:30277/onap/so/infra/serviceInstances/v6/95762b50-0244-4723-8fde-35f911db9263/networks \
+  -H 'Accept: application/json' \
+  -H 'Authorization: Basic SW5mcmFQb3J0YWxDbGllbnQ6cGFzc3dvcmQxJA==' \
+  -H 'Content-Type: application/json' \
+  -H 'X-FromAppId: AAI' \
+  -H 'X-TransactionId: get_aai_subscr' \
+  -H 'cache-control: no-cache' \
+  -d '{
+  "requestDetails": {
+      "requestInfo": {
+          "instanceName": "my_network_01",
+          "source": "VID",
+          "suppressRollback": false,
+          "requestorId": "demo",
+          "productFamilyId": "b9ac88f7-0e1b-462d-84ac-74c3c533217c"
+      },
+      "modelInfo": {
+          "modelType": "network",
+          "modelInvariantId": "0070b65c-48cb-4985-b4df-7c67ca99cd95",
+          "modelVersionId": "4f738bed-e804-4765-8d22-07bb4d11f14b",
+          "modelName": "Generic NeutronNet",
+          "modelVersion": "1.0",
+          "modelCustomizationId": "95534a95-dc8d-4ffb-89c7-091e2c49b55d",
+          "modelCustomizationName": "Generic NeutronNet 0"
+      },
+    "requestParameters": {
+      "userParams": [],
+      "aLaCarte": true,
+    "testApi": "VNF_API"
+    },
+    "cloudConfiguration": {
+      "lcpCloudRegionId": "my_cloud_site",
+      "tenantId": "5906b9b8fd9642df9ba1c9e290063439"
+    },
+      "lineOfBusiness": {
+          "lineOfBusinessName": "Test_LOB"
+      },
+      "platform": {
+          "platformName": "Test_platform"
+      },
+      "relatedInstanceList": [{
+          "relatedInstance": {
+              "instanceId": "95762b50-0244-4723-8fde-35f911db9263",
+              "modelInfo": {
+                  "modelType": "service",
+                  "modelName": "my_service_model_name",
+                  "modelInvariantId": "11265d8c-2cc2-40e5-95d8-57cad81c18da",
+                  "modelVersion": "1.0",
+                  "modelVersionId": "0d463b0c-e559-4def-8d7b-df64cfbd3159"
+              }
+          }
+      }]
+  }
+}'
diff --git a/docs/guides/onap-user/instantiate/instantiation/so2/index.rst b/docs/guides/onap-user/instantiate/instantiation/so2/index.rst
new file mode 100644
index 000000000..314fef10f
--- /dev/null
+++ b/docs/guides/onap-user/instantiate/instantiation/so2/index.rst
@@ -0,0 +1,187 @@
+.. This work is licensed under a Creative Commons Attribution 4.0
+.. International License. http://creativecommons.org/licenses/by/4.0
+.. Copyright 2019 ONAP Contributors.  All rights reserved.
+
+.. _doc_guide_user_ser_inst:
+
+
+Macro mode Service Instantiation via ONAP SO API
+================================================
+
+Using Macro mode, you have to build and send only one request to ONAP SO
+
+In that request you need to indicate all object instances
+that you want to be instantiated.
+
+Reminder : ONAP SO in Macro mode will perform the VNF parameters/values
+assignment based on CDS Blueprint templates
+that are supposed to be defined during Design and Onboard steps.
+That means ONAP has all information
+to be able to get all necessary values by itself (there is no longer need
+for an Operator to provide "SDNC preload").
+
+Request Example :
+
+::
+
+  curl -X POST \
+    'http://{{k8s}}:30277/onap/so/infra/serviceInstantiation/v7/serviceInstances' \
+    -H 'Content-Type: application/json' \
+    -H 'cache-control: no-cache' \
+    -d '{
+    "requestDetails": {
+      "subscriberInfo": {
+        "globalSubscriberId": "Demonstration"
+      },
+      "requestInfo": {
+        "suppressRollback": false,
+        "productFamilyId": "a9a77d5a-123e-4ca2-9eb9-0b015d2ee0fb",
+        "requestorId": "adt",
+        "instanceName": "{{cds-instance-name}}",
+        "source": "VID"
+      },
+      "cloudConfiguration": {
+        "lcpCloudRegionId": "fr1",
+        "tenantId": "6270eaa820934710960682c506115453"
+      },
+      "requestParameters": {
+        "subscriptionServiceType": "vFW",
+        "userParams": [
+          {
+            "Homing_Solution": "none"
+          },
+          {
+            "service": {
+              "instanceParams": [
+
+              ],
+              "instanceName": "{{cds-instance-name}}",
+              "resources": {
+                "vnfs": [
+                  {
+                    "modelInfo": {
+                  "modelName": "{{vnf-modelinfo-modelname}}",
+                  "modelVersionId": "{{vnf-modelinfo-modeluuid}}",
+                  "modelInvariantUuid": "{{vnf-modelinfo-modelinvariantuuid}}",
+                  "modelVersion": "1.0",
+                  "modelCustomizationId": "{{vnf-modelinfo-modelcustomizationuuid}}",
+                  "modelInstanceName": "{{vnf-modelinfo-modelinstancename}}"
+                    },
+                    "cloudConfiguration": {
+                      "lcpCloudRegionId": "fr1",
+                      "tenantId": "6270eaa820934710960682c506115453"
+                    },
+                    "platform": {
+                      "platformName": "test"
+                    },
+                    "lineOfBusiness": {
+                      "lineOfBusinessName": "someValue"
+                    },
+                    "productFamilyId": "a9a77d5a-123e-4ca2-9eb9-0b015d2ee0fb",
+                    "instanceName": "{{vnf-modelinfo-modelinstancename}}",
+                    "instanceParams": [
+                      {
+                        "onap_private_net_id": "olc-private",
+                        "onap_private_subnet_id": "olc-private",
+                        "pub_key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQCwj7uJMyKiP1ogEsZv5kKDFw9mFNhxI+woR3Tuv8vjfNnqdB1GfSnvTFyNbdpyNdR8BlljkiZ1SlwJLEkvPk0HpOoSVVek/QmBeGC7mxyRcpMB2cNQwjXGfsVrforddXOnOkj+zx1aNdVGMc52Js3pex8B/L00H68kOcwP26BI1o77Uh+AxjOkIEGs+wlWNUmXabLDCH8l8IJk9mCTruKEN9KNj4NRZcaNC+XOz42SyHV9RT3N6efp31FqKzo8Ko63QirvKEEBSOAf9VlJ7mFMrGIGH37AP3JJfFYEHDdOA3N64ZpJLa39y25EWwGZNlWpO/GW5bNjTME04dl4eRyd",
+                        "image_name": "Ubuntu 14.04",
+                        "flavor_name":"s1.cw.small-1"
+                      }
+                    ],
+                    "vfModules": [
+                      {
+                        "modelInfo": {
+                          "modelName": "{{vnf-vfmodule-0-modelinfo-modelname}}",
+                          "modelVersionId": "{{vnf-vfmodule-0-modelinfo-modeluuid}}",
+                         "modelInvariantUuid": "{{vnf-vfmodule-0-modelinfo-modelinvariantuuid}}",
+                          "modelVersion": "1",
+                          "modelCustomizationId": "{{vnf-vfmodule-0-modelinfo-modelcustomizationuuid}}"
+                         },
+                        "instanceName": "{{vnf-vfmodule-0-modelinfo-modelname}}",
+                        "instanceParams": [
+                                                   {
+                            "sec_group": "olc-open",
+                            "public_net_id": "olc-net"
+                          }
+                        ]
+                      },
+                      {
+                        "modelInfo": {
+                          "modelName": "{{vnf-vfmodule-1-modelinfo-modelname}}",
+                          "modelVersionId": "{{vnf-vfmodule-1-modelinfo-modeluuid}}",
+                          "modelInvariantUuid": "{{vnf-vfmodule-1-modelinfo-modelinvariantuuid}}",
+                          "modelVersion": "1",
+                          "modelCustomizationId": "{{vnf-vfmodule-1-modelinfo-modelcustomizationuuid}}"
+                         },
+                        "instanceName": "{{vnf-vfmodule-1-modelinfo-modelname}}",
+                        "instanceParams": [
+                          {
+                            "sec_group": "olc-open",
+                            "public_net_id": "olc-net"
+                          }
+                        ]
+                      },
+                      {
+                        "modelInfo": {
+                          "modelName": "{{vnf-vfmodule-2-modelinfo-modelname}}",
+                          "modelVersionId": "{{vnf-vfmodule-2-modelinfo-modeluuid}}",
+                          "modelInvariantUuid": "{{vnf-vfmodule-2-modelinfo-modelinvariantuuid}}",
+                          "modelVersion": "1",
+                          "modelCustomizationId": "{{vnf-vfmodule-2-modelinfo-modelcustomizationuuid}}"
+                         },
+                        "instanceName": "{{vnf-vfmodule-2-modelinfo-modelname}}",
+                        "instanceParams": [
+                          {
+                            "sec_group": "olc-open",
+                            "public_net_id": "olc-net"
+                          }
+                        ]
+                      },
+                      {
+                        "modelInfo": {
+                          "modelName": "{{vnf-vfmodule-3-modelinfo-modelname}}",
+                          "modelVersionId": "{{vnf-vfmodule-3-modelinfo-modeluuid}}",
+                          "modelInvariantUuid": "{{vnf-vfmodule-3-modelinfo-modelinvariantuuid}}",
+                          "modelVersion": "1",
+                          "modelCustomizationId": "{{vnf-vfmodule-3-modelinfo-modelcustomizationuuid}}"
+                        },
+                        "instanceName": "{{vnf-vfmodule-3-modelinfo-modelname}}",
+                        "instanceParams": [
+                          {
+                            "sec_group": "olc-open",
+                            "public_net_id": "olc-net"
+                          }
+                        ]
+                      }
+                    ]
+                  }
+                ]
+              },
+              "modelInfo": {
+                "modelVersion": "1.0",
+          "modelVersionId": "{{service-uuid}}",
+          "modelInvariantId": "{{service-invariantUUID}}",
+          "modelName": "{{service-name}}",
+                "modelType": "service"
+              }
+            }
+          }
+        ],
+        "aLaCarte": false
+      },
+      "project": {
+        "projectName": "Project-Demonstration"
+      },
+      "owningEntity": {
+        "owningEntityId": "24ef5425-bec4-4fa3-ab03-c0ecf4eaac96",
+        "owningEntityName": "OE-Demonstration"
+      },
+      "modelInfo": {
+        "modelVersion": "1.0",
+          "modelVersionId": "{{service-uuid}}",
+          "modelInvariantId": "{{service-invariantUUID}}",
+          "modelName": "{{service-name}}",
+       "modelType": "service"
+      }
+    }
+  }'
diff --git a/docs/guides/onap-user/instantiate/instantiation/uui/index.rst b/docs/guides/onap-user/instantiate/instantiation/uui/index.rst
new file mode 100644
index 000000000..dd57c0891
--- /dev/null
+++ b/docs/guides/onap-user/instantiate/instantiation/uui/index.rst
@@ -0,0 +1,14 @@
+.. This work is licensed under a Creative Commons Attribution 4.0
+.. International License. http://creativecommons.org/licenses/by/4.0
+.. Copyright 2019 ONAP Contributors.  All rights reserved.
+
+
+e2eServiceInstance mode via ONAP UUI Portal
+===========================================
+
+
+.. toctree::
+   :maxdepth: 1
+   :titlesonly:
+
+   ../../../../submodules/usecase-ui.git/docs/platform/installation/user-guide/index.rst
diff --git a/docs/guides/onap-user/instantiate/instantiation/vid/index.rst b/docs/guides/onap-user/instantiate/instantiation/vid/index.rst
new file mode 100644
index 000000000..78b4e4c03
--- /dev/null
+++ b/docs/guides/onap-user/instantiate/instantiation/vid/index.rst
@@ -0,0 +1,13 @@
+.. This work is licensed under a Creative Commons Attribution 4.0
+.. International License. http://creativecommons.org/licenses/by/4.0
+.. Copyright 2019 ONAP Contributors.  All rights reserved.
+
+
+Alacarte mode Service Instantiation via ONAP VID Portal
+=======================================================
+
+. toctree::
+   :maxdepth: 1
+   :titlesonly:
+
+   ../../../../submodules/vid.git/docs/humaninterfaces.rst
diff --git a/docs/guides/onap-user/instantiate/pre_instantiation/index.rst b/docs/guides/onap-user/instantiate/pre_instantiation/index.rst
new file mode 100644
index 000000000..ca9af13d7
--- /dev/null
+++ b/docs/guides/onap-user/instantiate/pre_instantiation/index.rst
@@ -0,0 +1,225 @@
+.. This work is licensed under a Creative Commons Attribution 4.0
+.. International License. http://creativecommons.org/licenses/by/4.0
+.. Copyright 2019 ONAP Contributors.  All rights reserved.
+
+.. _doc_guide_user_pre_ser-inst:
+
+
+Pre Service instantiation Operations
+====================================
+
+Several operations need to be performed after Service model distribution,
+but before instantiating a service.
+
+Those operations are only available via REST API requests.
+
+Various tools can be used to send REST API requests.
+
+Here after are examples using "curl" command line tool that you can use in
+a Unix Terminal.
+
+
+Declare owningEntity, lineOfBusiness, Platform and Project
+----------------------------------------------------------
+
+At one point during Service Instantiation, the user need to select values for
+those 4 parameters
+
+* Owning Entity
+* Line Of Business
+* Platform
+* Project
+
+
+Those parameters and values must be pre-declared in ONAP VID component
+using REST API
+
+Those informations will be available to all service instantiation
+(you only need to declare them once in ONAP)
+
+
+Example for "Owning Entity" named "Test"
+
+::
+
+  curl -X POST \
+    http://vid.api.simpledemo.onap.org:30238/vid/maintenance/category_parameter/owningEntity \
+    -H 'Accept-Encoding: gzip, deflate' \
+    -H 'Content-Type: application/json' \
+    -H 'cache-control: no-cache' \
+    -d '{
+      "options": ["Test"]
+  }'
+
+Example for "platform" named "Test_Platform"
+
+::
+
+  curl -X POST \
+    http://vid.api.simpledemo.onap.org:30238/vid/maintenance/category_parameter/platform \
+    -H 'Content-Type: application/json' \
+    -H 'cache-control: no-cache' \
+    -d '{
+      "options": [""Test_Platform"]
+  }'
+
+Example for "line of business" named "Test_LOB"
+
+::
+
+  curl -X POST \
+  http://vid.api.simpledemo.onap.org:30238/vid/maintenance/category_parameter/lineOfBusiness \
+  -H 'Content-Type: application/json' \
+  -H 'cache-control: no-cache' \
+  -d '{
+    "options": ["Test_LOB"]
+  }'
+
+Example for "project" named "Test_project"
+
+::
+
+  curl -X POST \
+    http://vid.api.simpledemo.onap.org:30238/vid/maintenance/category_parameter/project \
+    -H 'Content-Type: application/json' \
+    -H 'cache-control: no-cache' \
+    -d '{
+      "options": ["Test_project"]
+  }'
+
+
+
+
+Declare a customer
+------------------
+
+Each time you have a new customer, you will need to perform those operations
+
+This operation is using ONAP AAI REST API
+
+Any service instance need to be linked to a customer
+
+in the query path, you put the customer_name
+
+in the query body you put the customer name again
+
+Here after an example to declare a customer named "my_customer_name"
+
+
+::
+
+  curl -X PUT \
+    https://aai.api.sparky.simpledemo.onap.org:30233/aai/v16/business/customers/customer/my_customer_name \
+    -H 'Accept: application/json' \
+    -H 'Authorization: Basic QUFJOkFBSQ==' \
+    -H 'Content-Type: application/json' \
+    -H 'X-FromAppId: AAI' \
+    -H 'X-TransactionId: 808b54e3-e563-4144-a1b9-e24e2ed93d4f' \
+    -H 'cache-control: no-cache' \
+    -d '{
+      "global-customer-id": "my_customer_name",
+      "subscriber-name": "my_customer_name",
+      "subscriber-type": "INFRA"
+  }' -k
+
+
+check customers in ONAP AAI (you should see if everything ok in the response)
+
+::
+
+  curl -X GET \
+    https://aai.api.sparky.simpledemo.onap.org:30233/aai/v16/business/customers \
+    -H 'Accept: application/json' \
+    -H 'Authorization: Basic QUFJOkFBSQ==' \
+    -H 'Content-Type: application/json' \
+    -H 'X-FromAppId: AAI' \
+    -H 'X-TransactionId: 808b54e3-e563-4144-a1b9-e24e2ed93d4f' \
+    -H 'cache-control: no-cache' -k
+
+
+Associate Service Model to Customer
+-----------------------------------
+
+
+This operation is using ONAP AAI REST API
+
+in the query path, you put the customer_name and the service model name
+
+in the query body you put the service model UUID
+
+::
+
+  curl -X PUT \
+    https://aai.api.sparky.simpledemo.onap.org:30233/aai/v16/business/customers/customer/my_customer_name/service-subscriptions/service-subscription/my_service_model_name \
+    -H 'Accept: application/json' \
+    -H 'Authorization: Basic QUFJOkFBSQ==' \
+    -H 'Content-Type: application/json' \
+    -H 'Postman-Token: d4bc4991-a518-4d75-8a87-674ba44bf13a' \
+    -H 'X-FromAppId: AAI' \
+    -H 'X-TransactionId: 808b54e3-e563-4144-a1b9-e24e2ed93d4f' \
+    -H 'cache-control: no-cache' \
+    -d '{
+      "service-id": "11265d8c-2cc2-40e5-95d8-57cad81c18da"
+  }' -k
+
+
+
+
+Associate Cloud Site to Customer
+--------------------------------
+
+in the query path, you put the customer_name and the service model name
+
+in the query body you put the cloud owner name, the cloud site name,
+the tenant id and the tenant name
+
+
+::
+
+  curl -X PUT \
+    https://aai.api.sparky.simpledemo.onap.org:30233/aai/v16/business/customers/customer/my_customer_name/service-subscriptions/service-subscription/my_service_model_name/relationship-list/relationship \
+    -H 'Accept: application/json' \
+    -H 'Authorization: Basic QUFJOkFBSQ==' \
+    -H 'Content-Type: application/json' \
+    -H 'Postman-Token: 11ea9a9e-0dc8-4d20-8a78-c75cd6928916' \
+    -H 'X-FromAppId: AAI' \
+    -H 'X-TransactionId: 808b54e3-e563-4144-a1b9-e24e2ed93d4f' \
+    -H 'cache-control: no-cache' \
+    -d '{
+      "related-to": "tenant",
+      "related-link": "/aai/v16/cloud-infrastructure/cloud-regions/cloud-region/my_cloud_owner_name/my_cloud_site_name/tenants/tenant/234a9a2dc4b643be9812915b214cdbbb",
+      "relationship-data": [
+          {
+              "relationship-key": "cloud-region.cloud-owner",
+              "relationship-value": "my_cloud_owner_name"
+          },
+          {
+              "relationship-key": "cloud-region.cloud-region-id",
+              "relationship-value": "my_cloud_site_name"
+          },
+          {
+              "relationship-key": "tenant.tenant-id",
+              "relationship-value": "234a9a2dc4b643be9812915b214cdbbb"
+          }
+      ],
+      "related-to-property": [
+          {
+              "property-key": "tenant.tenant-name",
+              "property-value": "my_tenant_name"
+          }
+      ]
+  }' -k
+
+
+check (you should see if everything ok in the response)
+
+::
+
+  curl -X GET \
+    'https://aai.api.sparky.simpledemo.onap.org:30233/aai/v16/business/customers/customer/my_customer_name/service-subscriptions?depth=all' \
+    -H 'Accept: application/json' \
+    -H 'Authorization: Basic QUFJOkFBSQ==' \
+    -H 'Content-Type: application/json' \
+    -H 'X-FromAppId: AAI' \
+    -H 'X-TransactionId: 808b54e3-e563-4144-a1b9-e24e2ed93d4f' \
+    -H 'cache-control: no-cache' -k