Add doc about ONAP Postman collection

Issue-ID: INT-1185

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

8 files changed, 191 insertions, 0 deletions

diff --git a/docs/docs_postman.rst b/docs/docs_postman.rst
new file mode 100644
index 000000000..54d7b4f58
--- /dev/null
+++ b/docs/docs_postman.rst
@@ -0,0 +1,191 @@
+.. 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.
+
+.. _postman-guides:
+
+Test ONAP API with Postman
+==========================
+
+Postman
+-------
+
+Postman is a tool that allows a user to run REST API.
+
+The user defines the API requests and has the possibility to group them
+in files called a "Collections".
+
+The user can then run each individual API request or run a complete collection.
+
+Postman includes the possibility to define "environment" variables.
+
+An API request can then get or set a value from/to that "environment" variable.
+
+Get and install Postman tool on your own machine (Linux/windows).
+
+Postman is available here: https://www.getpostman.com/
+
+
+ONAP Postman collections
+------------------------
+
+ONAP Integration project provides several Postman collections with two
+environment files.
+
+Those Postman Collections will allow a Developer to experiment various ONAP API
+on various ONAP components (SDC, NBI, SO, AAI, SDNC)
+
+- declare a vendor
+- declare a VSP
+- upload a package
+- declare a VF based on the VSP
+- declare a Service composed of the VF and a Virtual Link
+- distribute all those informations
+- declare a customer, a service subscription
+- declare OwningEntity, Platform...
+- declare a Complex, Cloud Region, Tenant
+- associate customer/service/tenant
+- declare a service instance via a serviceOrder
+- declare a vnf
+- declare a vf-module
+- declare a network
+
+A collection is also provided to delete objects
+(reminder: it is not possible to delete object in SDC)
+
+They have been tested with Onap Dublin (they are not all compatible with
+Casablanca, and there is not guaranty about ONAP "master" as API definition
+can change)
+
+
+Download ONAP Postman collections
+---------------------------------
+
+From your machine, git clone the ONAP Integration project.
+
+::
+
+  git clone "https://gerrit.onap.org/r/integration"
+
+
+Import ONAP Postman collections
+-------------------------------
+
+ONAP Postman collection are in the repository integration/test/postman
+
+Launch Postman tool
+
+import all ONAP Collections into Postman
+
+.. figure:: files/postman/import.png
+   :align: center
+
+And you should see all the collections into Postman
+
+.. figure:: files/postman/collections.png
+   :align: center
+
+Each collection is made of several API operations
+
+.. figure:: files/postman/collection-detail.png
+   :align: center
+
+
+Running ONAP Postman collections
+--------------------------------
+
+Running all those collections, in the order, from 1 to 10 will create a lot of
+objects in ONAP components :
+
+- SDC : vendor, VSP, zip file upload, VF from VSP, Service, add VF to Service
+- VID : OwningEntity, LineOfBusiness, Project, Platform
+- AAI : customer, subscription, cloud region, tenant
+- NBI : serviceOrder to add a service instance, serviceOrder to delete
+  a service instance
+
+The order is very important because a lot of API requests will need the API
+response from the previous operation o get and set some variable values.
+
+.. figure:: files/postman/collection-detail-test.png
+   :align: center
+
+It is possible to run the complete collection using Postman
+
+.. figure:: files/postman/run.png
+   :align: center
+
+You need, a zip file that contains Heat files for a VNF.
+
+Collection 3 is about uploading that file into ONAP SDC.
+
+.. figure:: files/postman/zipfile.png
+   :align: center
+
+Before running those collections, once in Postman, you need to have a look
+at "globals" environment parameters.
+
+.. figure:: files/postman/globals.png
+   :align: center
+
+All variables that begin by "auto" must NOT be changed (they will be modified
+using API response).
+
+All other variables must be adapted to your needs.
+
+In particular, you need to put your own values for cloud_region_id, tenant_name
+and tenant_id to fit with the place where you will instantiate the VNF.
+
+
+::
+
+  service:freeradius
+  vf_name:integration_test_VF_freeradius
+  vsp_name:integration_test_VSP
+  vendor_name:onap_integration_vendor
+  owning_entity:integration_test_OE
+  platform:integration_test_platform
+  project:integration_test_project
+  lineofbusiness:integration_test_LOB
+  customer_name:generic
+  cloud_owner_name:OPNFV
+  cloud_region_id:RegionOne
+  tenant_name:openlab-vnfs
+  tenant_id:234a9a2dc4b643be9812915b214cdbbb
+  externalId:integration_test_BSS-order-001
+  service_instance_name:integration_test_freeradius_instance_001
+  listener_url:http://10.4.2.65:8080/externalapi/listener/v1/listener
+
+
+Using Newman
+------------
+
+Newman is a tool that allow to run postman collections via command-line
+
+On a linux server, with Docker installed on it, run those lines:
+
+::
+
+  git clone https://gitlab.com/Orange-OpenSource/lfn/onap/onap-tests.git
+  cd onap-tests/postman
+  sudo apt-get -y install zip
+  USECASE=$'ubuntu16'
+  zip -j $USECASE.zip ../onap_tests/templates/heat_files/$USECASE/*
+  TAB=$'\t\t\t\t\t\t\t'
+  sed -i -e "s/.*src.*/$TAB\"src\": \"$USECASE.zip\"/" 03_Onboard_VSP_part2.postman_collection.json
+  docker pull postman/newman:alpine
+  docker run --network="host" --volume="/home/debian/rene/onap-tests/postman:/etc/newman" postman/newman:alpine run 01_Onboard_Vendor.postman_collection.json --environment integration_test_urls.postman_environment.json --globals globals.postman_globals.json --export-globals globals.postman_globals.json --reporters cli,json --reporter-cli-no-assertions --reporter-cli-no-console
+  docker run --network="host" --volume="/home/debian/rene/onap-tests/postman:/etc/newman" postman/newman:alpine run 02_Onboard_VSP_part1.postman_collection.json --environment integration_test_urls.postman_environment.json --globals globals.postman_globals.json --export-globals globals.postman_globals.json
+  docker run --network="host" --volume="/home/debian/rene/onap-tests/postman:/etc/newman" postman/newman:alpine run 03_Onboard_VSP_part2.postman_collection.json --environment integration_test_urls.postman_environment.json --globals globals.postman_globals.json --export-globals globals.postman_globals.json
+  docker run --network="host" --volume="/home/debian/rene/onap-tests/postman:/etc/newman" postman/newman:alpine run 04_Onboard_VSP_part3.postman_collection.json --environment integration_test_urls.postman_environment.json --globals globals.postman_globals.json --export-globals globals.postman_globals.json
+  docker run --network="host" --volume="/home/debian/rene/onap-tests/postman:/etc/newman" postman/newman:alpine run 05_Onboard_VF.postman_collection.json --environment integration_test_urls.postman_environment.json --globals globals.postman_globals.json --export-globals globals.postman_globals.json
+  docker run --network="host" --volume="/home/debian/rene/onap-tests/postman:/etc/newman" postman/newman:alpine run 06_Onboard_Service.postman_collection.json --environment integration_test_urls.postman_environment.json --globals globals.postman_globals.json --export-globals globals.postman_globals.json
+  docker run --network="host" --volume="/home/debian/rene/onap-tests/postman:/etc/newman" postman/newman:alpine run 07_Declare_owningEntity_LineOfBusiness_project_platform.postman_collection.json --environment integration_test_urls.postman_environment.json --globals globals.postman_globals.json --export-globals globals.postman_globals.json
+  docker run --network="host" --volume="/home/debian/rene/onap-tests/postman:/etc/newman" postman/newman:alpine run 08_Declare_Customer_Service_Subscription_Cloud.postman_collection.json --insecure --environment integration_test_urls.postman_environment.json --globals globals.postman_globals.json --export-globals globals.postman_globals.json
+  docker run --network="host" --volume="/home/debian/rene/onap-tests/postman:/etc/newman" postman/newman:alpine run 10_instantiate_service_vnf_vfmodule.postman_collection.json --environment integration_test_urls.postman_environment.json --globals globals.postman_globals.json --export-globals globals.postman_globals.json --reporters cli,json --reporter-cli-no-assertions --reporter-cli-no-console
+
+All collections are processed, then you can see results and you will
+also obtain result json files in the onap-tests/postamn/newman directory
+
+Of course you can adapt globals variables in globals.postman_globals.json
+or change the USECASE=$'ubuntu16' value to onboard any heat template located
+in onap_tests/templates/heat_files directory
diff --git a/docs/files/postman/collection-detail-test.png b/docs/files/postman/collection-detail-test.png
new file mode 100755
index 000000000..b64cd7ffa
--- /dev/null
+++ b/docs/files/postman/collection-detail-test.png
diff --git a/docs/files/postman/collection-detail.png b/docs/files/postman/collection-detail.png
new file mode 100755
index 000000000..59b7db266
--- /dev/null
+++ b/docs/files/postman/collection-detail.png
diff --git a/docs/files/postman/collections.png b/docs/files/postman/collections.png
new file mode 100755
index 000000000..4469cdb9d
--- /dev/null
+++ b/docs/files/postman/collections.png
diff --git a/docs/files/postman/globals.png b/docs/files/postman/globals.png
new file mode 100755
index 000000000..f3ae23978
--- /dev/null
+++ b/docs/files/postman/globals.png
diff --git a/docs/files/postman/import.png b/docs/files/postman/import.png
new file mode 100755
index 000000000..122c867ce
--- /dev/null
+++ b/docs/files/postman/import.png
diff --git a/docs/files/postman/run.png b/docs/files/postman/run.png
new file mode 100755
index 000000000..35c4d5b1f
--- /dev/null
+++ b/docs/files/postman/run.png
diff --git a/docs/files/postman/zipfile.png b/docs/files/postman/zipfile.png
new file mode 100755
index 000000000..a7cfa89ea
--- /dev/null
+++ b/docs/files/postman/zipfile.png