Merge "CDS API Reference add workflow tutorial"

7 files changed, 273 insertions, 46 deletions

diff --git a/docs/api-reference/bp-processor.rst b/docs/api-reference/bp-processor.rst
index c4694c0bd..00dd7cce6 100644
--- a/docs/api-reference/bp-processor.rst
+++ b/docs/api-reference/bp-processor.rst
@@ -13,6 +13,19 @@ which is automatically created during CDS build process by Swagger Maven Plugin.
 also included. Endpoints can also be described using this template
 :download:`api-doc-template.rst <api-doc-template.rst>` but this is not the prefered way to describe the CDS API.
 
+You can find a sample workflow tutorial :ref:`below <workflow-tutorial>` which will show how to use the endpoints
+in the right order. This will give you a better understanding of the CDS Blueprint Processor API.
+
+Getting Started
+-----------------
+
+If you cant access a running CDS Blueprint Processor yet, you can choose one of the below options to run it. 
+Afterwards you can start trying out the API.
+
+* CDS in Microk8s: https://wiki.onap.org/display/DW/Running+CDS+on+Microk8s (RDT link to be added)
+* CDS in Minikube: https://wiki.onap.org/display/DW/Running+CDS+in+minikube (RDT link to be added)
+* CDS in an IDE:  :ref:`Running BP Processor Microservice in an IDE <running_bp_processor_in_ide>`
+
 Authorization
 -----------------
 
@@ -151,4 +164,87 @@ API Reference
    rendered completely, e.g. the request body. Use your favorite Swagger Editor and paste the swagger file
    to get a complete view of the API reference, e.g. on https://editor.swagger.io/.
 
-.. swaggerv2doc:: media/cds-bp-processor-api-swagger.json
\ No newline at end of file
+.. swaggerv2doc:: media/cds-bp-processor-api-swagger.json
+
+
+
+.. _workflow-tutorial:
+
+Workflow Tutorial
+------------------
+
+Introduction
+~~~~~~~~~~~~~
+
+This section will show a basic workflow how to proceed a CBA. For this we will follow
+the :ref:`PNF Simulator use case <pnf_simulator_use_case>` guide. We will use the same CBA but since this CBA is loaded during
+bootstrap per default we will first delete it and afterwards manually enrich and save it in CDS.
+The referred use case shows how the day-n configuration is assigned and deployed to a PNF through CDS.
+You don't necessarily need a netconf server (which will act as an PNF Simulator) running to get a understanding about
+this workflow tutorial. Just take care that without a set up netconf server the day-n configuration deployment will fail
+in the last step.
+
+Use the Postman Collection from the referred use case to get sample requests for the following steps:
+:download:`json <../usecases/media/pnf-simulator.postman_collection.json>`.
+
+The CBA which we are using is downloadable here :download:`zip <media/workflow-tutorial-cba.zip>`. Hint: this CBA is
+also included in the CDS source code for bootstrapping.
+
+Set up CDS
+~~~~~~~~~~
+
+If not done before, run `Bootrap` request which will call Bootstrap API of CDS (``POST /api/v1/blueprint-model/bootstrap``)
+to load all the CDS default model artifacts into CDS. You should get HTTP status 200 for the below command.
+
+Call `Get Blueprints` request to get all blueprint models which are saved in CDS. This will call the ``GET /api/v1/blueprint-model``
+endpoint. You will see the blueprint model ``"artifactName": "pnf_netconf"`` which is loaded by calling bootstrap since Guilin release.
+Since we manually want to load the CBA delete the desired CBA from CDS first through calling the delete endpoint
+``DELETE /api/v1/blueprint-model/name/{name}/version/{version}``. If you call `Get Blueprints` again you can see that the
+``pnf_netconf`` CBA is missing now.
+
+Because the CBA contains a custom data dictionary we need to push the custom entries to CDS first through calling `Data Dictionary` request.
+Actually the custom entries are also already loaded through bootstrap but just pretend they are not present in CDS so far.
+
+.. note::
+   For every data dictionary entry CDS API needs to be called seperately. The postman collection contains a loop to
+   go through all custom entries and call data dictionary endpoint seperately. To execute this loop,
+   open `Runner` in Postman and run `Data Dictionary` request like it is shown in the picture below.
+
+   |imageDDPostmanRunner|
+
+
+Enrichment
+~~~~~~~~~~~~
+
+Enrich the blueprint through executing the `Enrich Blueprint` request. Take care to provide the CBA file which you
+can download here :download:`zip <media/workflow-tutorial-cba.zip>` in the request body. After the request got executed
+download the response body like shown in the picture below, this will be your enriched CBA file.
+
+|saveResponseImage|
+
+
+Deploy/Save the Blueprint
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Run `Save Blueprint` request to save/deploy the Blueprint into the CDS database. Take care to provide the enriched
+CBA file which you downloaded earlier in the request body.
+
+After that you should see the new model ``"artifactName": "pnf_netconf"`` by calling `Get Blueprints` request.
+
+An alternative would be to use ``POST /api/v1/blueprint-model/publish`` endpoint, which would also validate the CBA.
+For doing enrichment and saving the CBA in a single call ``POST /api/v1/blueprint-model/enrichandpublish`` could also be used.
+
+Config-Assign / Config-Deploy
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+From now on you can continue with the :ref:`PNF Simulator use case <pnf_simulator_use_case_config_assign_deploy>` from section
+`Config-assign and config-deploy` to finish the workflow tutorial. The provided Postman collection already contains all
+the needed requests also for this part so you don't need to create the calls and payloads manually.
+Take care that the last step will fail if you don't have a netconf server set up.
+
+
+.. |imageDDPostmanRunner| image:: media/dd-postman-runner.png
+   :width: 500pt
+
+.. |saveResponseImage| image:: media/save-response-postman.png
+   :width: 500pt
\ No newline at end of file
diff --git a/docs/api-reference/media/dd-postman-runner.png b/docs/api-reference/media/dd-postman-runner.png
new file mode 100644
index 000000000..747e86231
--- /dev/null
+++ b/docs/api-reference/media/dd-postman-runner.png
diff --git a/docs/api-reference/media/save-response-postman.png b/docs/api-reference/media/save-response-postman.png
new file mode 100644
index 000000000..d46c0fe21
--- /dev/null
+++ b/docs/api-reference/media/save-response-postman.png
diff --git a/docs/api-reference/media/workflow-tutorial-cba.zip b/docs/api-reference/media/workflow-tutorial-cba.zip
new file mode 100644
index 000000000..c60a07c68
--- /dev/null
+++ b/docs/api-reference/media/workflow-tutorial-cba.zip
diff --git a/docs/usecases/media/pnf-simulator.postman_collection.json b/docs/usecases/media/pnf-simulator.postman_collection.json
index cab40da85..b160d061a 100644
--- a/docs/usecases/media/pnf-simulator.postman_collection.json
+++ b/docs/usecases/media/pnf-simulator.postman_collection.json
@@ -1,6 +1,6 @@
 {
 	"info": {
-		"_postman_id": "0175f488-96af-4253-ad35-d2a670330091",
+		"_postman_id": "835c7d3a-d5c4-4f5b-a80f-b2870da7850c",
 		"name": "CDS PNF Simulator Use Case",
 		"description": "This collection contains all API calls to do the \"PNF Simulator Day-N config-assign and config-deploy use case\" in CDS. ",
 		"schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
@@ -42,10 +42,7 @@
 				],
 				"body": {
 					"mode": "raw",
-					"raw": "{\r\n\"loadModelType\" : true,\r\n\"loadResourceDictionary\" : true,\r\n\"loadCBA\" : true\r\n}",
-					"options": {
-						"raw": {}
-					}
+					"raw": "{\r\n\"loadModelType\" : true,\r\n\"loadResourceDictionary\" : true,\r\n\"loadCBA\" : true\r\n}"
 				},
 				"url": {
 					"raw": "http://{{host}}:{{port}}/api/v1/blueprint-model/bootstrap",
@@ -81,10 +78,7 @@
 						],
 						"body": {
 							"mode": "raw",
-							"raw": "{\r\n\"loadModelType\" : false,\r\n\"loadResourceDictionary\" : true,\r\n\"loadCBA\" : false\r\n}",
-							"options": {
-								"raw": {}
-							}
+							"raw": "{\r\n\"loadModelType\" : false,\r\n\"loadResourceDictionary\" : true,\r\n\"loadCBA\" : false\r\n}"
 						},
 						"url": {
 							"raw": "http://localhost:8081/api/v1/blueprint-model/bootstrap",
@@ -207,10 +201,7 @@
 				],
 				"body": {
 					"mode": "raw",
-					"raw": "{\r\n\"loadModelType\" : true,\r\n\"loadResourceDictionary\" : true,\r\n\"loadCBA\" : false\r\n}",
-					"options": {
-						"raw": {}
-					}
+					"raw": "{\r\n\"loadModelType\" : true,\r\n\"loadResourceDictionary\" : true,\r\n\"loadCBA\" : false\r\n}"
 				},
 				"url": {
 					"raw": "http://{{host}}:{{port}}/api/v1/blueprint-model",
@@ -245,10 +236,167 @@
 						],
 						"body": {
 							"mode": "raw",
-							"raw": "{\r\n\"loadModelType\" : false,\r\n\"loadResourceDictionary\" : true,\r\n\"loadCBA\" : false\r\n}",
-							"options": {
-								"raw": {}
+							"raw": "{\r\n\"loadModelType\" : false,\r\n\"loadResourceDictionary\" : true,\r\n\"loadCBA\" : false\r\n}"
+						},
+						"url": {
+							"raw": "http://localhost:8081/api/v1/blueprint-model/bootstrap",
+							"protocol": "http",
+							"host": [
+								"localhost"
+							],
+							"port": "8081",
+							"path": [
+								"api",
+								"v1",
+								"blueprint-model",
+								"bootstrap"
+							]
+						}
+					},
+					"status": "OK",
+					"code": 200,
+					"_postman_previewlanguage": "json",
+					"header": [
+						{
+							"key": "X-ONAP-RequestID",
+							"value": "b73253b6-d2be-4701-bdb2-31fa66b79a01"
+						},
+						{
+							"key": "X-ONAP-InvocationID",
+							"value": "b1a59296-fcf2-4435-b8de-9a2e9b9f4077"
+						},
+						{
+							"key": "X-ONAP-PartnerName",
+							"value": "cds-controller"
+						},
+						{
+							"key": "Vary",
+							"value": "Origin"
+						},
+						{
+							"key": "Vary",
+							"value": "Access-Control-Request-Method"
+						},
+						{
+							"key": "Vary",
+							"value": "Access-Control-Request-Headers"
+						},
+						{
+							"key": "Content-Type",
+							"value": "application/json"
+						},
+						{
+							"key": "Content-Length",
+							"value": "0"
+						},
+						{
+							"key": "Cache-Control",
+							"value": "no-cache, no-store, max-age=0, must-revalidate"
+						},
+						{
+							"key": "Pragma",
+							"value": "no-cache"
+						},
+						{
+							"key": "Expires",
+							"value": "0"
+						},
+						{
+							"key": "X-Content-Type-Options",
+							"value": "nosniff"
+						},
+						{
+							"key": "X-Frame-Options",
+							"value": "DENY"
+						},
+						{
+							"key": "X-XSS-Protection",
+							"value": "1 ; mode=block"
+						},
+						{
+							"key": "Referrer-Policy",
+							"value": "no-referrer"
+						}
+					],
+					"cookie": [],
+					"body": ""
+				}
+			]
+		},
+		{
+			"name": "Delete Blueprint Model loaded in Bootstrap",
+			"protocolProfileBehavior": {
+				"disabledSystemHeaders": {}
+			},
+			"request": {
+				"auth": {
+					"type": "basic",
+					"basic": [
+						{
+							"key": "password",
+							"value": "ccsdkapps",
+							"type": "string"
+						},
+						{
+							"key": "username",
+							"value": "ccsdkapps",
+							"type": "string"
+						}
+					]
+				},
+				"method": "DELETE",
+				"header": [
+					{
+						"key": "Content-Type",
+						"value": "application/json",
+						"disabled": true
+					},
+					{
+						"key": "",
+						"type": "text",
+						"value": "",
+						"disabled": true
+					}
+				],
+				"url": {
+					"raw": "http://{{host}}:{{port}}/api/v1/blueprint-model/name/pnf_netconf/version/1.0.0",
+					"protocol": "http",
+					"host": [
+						"{{host}}"
+					],
+					"port": "{{port}}",
+					"path": [
+						"api",
+						"v1",
+						"blueprint-model",
+						"name",
+						"pnf_netconf",
+						"version",
+						"1.0.0"
+					]
+				},
+				"description": "Delete a blueprint model identified by its name and version from CDS."
+			},
+			"response": [
+				{
+					"name": "CDS Bootstrap",
+					"originalRequest": {
+						"method": "POST",
+						"header": [
+							{
+								"key": "Content-Type",
+								"value": "application/json"
+							},
+							{
+								"key": "",
+								"value": "",
+								"type": "text",
+								"disabled": true
 							}
+						],
+						"body": {
+							"mode": "raw",
+							"raw": "{\r\n\"loadModelType\" : false,\r\n\"loadResourceDictionary\" : true,\r\n\"loadCBA\" : false\r\n}"
 						},
 						"url": {
 							"raw": "http://localhost:8081/api/v1/blueprint-model/bootstrap",
@@ -341,7 +489,6 @@
 				{
 					"listen": "prerequest",
 					"script": {
-						"id": "697ce54a-7333-4b86-9d51-9591f741ad7d",
 						"exec": [
 							"var allDD = pm.environment.get(\"allDD\");\r",
 							"\r",
@@ -517,7 +664,6 @@
 				{
 					"listen": "test",
 					"script": {
-						"id": "ba9ff38c-cfb4-4e76-a58c-11c28b62a394",
 						"exec": [
 							"var allDD = pm.environment.get(\"allDD\");\r",
 							"\r",
@@ -631,12 +777,9 @@
 						{
 							"key": "file",
 							"type": "file",
-							"src": "/home/jakob/CDS_Use_Cases/PNF-DEMO-ENRICHED_WORKING/pnf-demo.zip"
+							"src": "/home/jakob/Downloads/workflow-tutorial-cba.zip"
 						}
-					],
-					"options": {
-						"formdata": {}
-					}
+					]
 				},
 				"url": {
 					"raw": "http://{{host}}:{{port}}/api/v1/blueprint-model/enrich",
@@ -692,12 +835,9 @@
 						{
 							"key": "file",
 							"type": "file",
-							"src": "/home/jakob/CDS_Use_Cases/PNF-DEMO-ENRICHED_WORKING/pnf-demo.zip"
+							"src": "/home/jakob/Downloads/workflow-tutorial-cba-enriched.zip"
 						}
-					],
-					"options": {
-						"formdata": {}
-					}
+					]
 				},
 				"url": {
 					"raw": "http://{{host}}:{{port}}/api/v1/blueprint-model",
@@ -732,10 +872,7 @@
 						],
 						"body": {
 							"mode": "raw",
-							"raw": "{\r\n\"loadModelType\" : false,\r\n\"loadResourceDictionary\" : true,\r\n\"loadCBA\" : false\r\n}",
-							"options": {
-								"raw": {}
-							}
+							"raw": "{\r\n\"loadModelType\" : false,\r\n\"loadResourceDictionary\" : true,\r\n\"loadCBA\" : false\r\n}"
 						},
 						"url": {
 							"raw": "http://localhost:8081/api/v1/blueprint-model/bootstrap",
@@ -876,7 +1013,6 @@
 					"mode": "raw",
 					"raw": "{\n\n    \"actionIdentifiers\": {\n        \"mode\": \"sync\",\n        \"blueprintName\": \"pnf_netconf\",\n        \"blueprintVersion\": \"1.0.0\",\n        \"actionName\": \"config-assign\"\n    },\n    \"payload\": {\n        \"config-assign-request\": {\n            \"resolution-key\": \"day-1\",\n            \"config-assign-properties\": {\n                \"stream-count\": 5\n            }\n        }\n    },\n    \"commonHeader\": {\n        \"subRequestId\": \"143748f9-3cd5-4910-81c9-a4601ff2ea58\",\n        \"requestId\": \"e5eb1f1e-3386-435d-b290-d49d8af8db4c\",\n        \"originatorId\": \"SDNC_DG\"\n    }\n}",
 					"options": {
-						"formdata": {},
 						"raw": {
 							"language": "json"
 						}
@@ -953,7 +1089,6 @@
 					"mode": "raw",
 					"raw": "{\n    \"actionIdentifiers\": {\n        \"mode\": \"sync\",\n        \"blueprintName\": \"pnf_netconf\",\n        \"blueprintVersion\": \"1.0.0\",\n        \"actionName\": \"config-assign\"\n    },\n    \"payload\": {\n        \"config-assign-request\": {\n            \"resolution-key\": \"day-2\",\n            \"config-assign-properties\": {\n                \"stream-count\": 10\n            }\n        }\n    },\n    \"commonHeader\": {\n        \"subRequestId\": \"143748f9-3cd5-4910-81c9-a4601ff2ea58\",\n        \"requestId\": \"e5eb1f1e-3386-435d-b290-d49d8af8db4c\",\n        \"originatorId\": \"SDNC_DG\"\n    }\n}",
 					"options": {
-						"formdata": {},
 						"raw": {
 							"language": "json"
 						}
@@ -1030,7 +1165,6 @@
 					"mode": "raw",
 					"raw": "{\n\t\"actionIdentifiers\": {\n\t\t\"mode\": \"sync\",\n\t\t\"blueprintName\": \"pnf_netconf\",\n\t\t\"blueprintVersion\": \"1.0.0\",\n\t\t\"actionName\": \"config-deploy\"\n\t},\n\t\"payload\": {\n\t\t\"config-deploy-request\": {\n\t\t\t\"resolution-key\": \"day-1\",\n\t\t\t\t\"pnf-ipv4-address\": \"{{pnf-ipv4-address}}\",\n                \"netconf-username\": \"{{netconf-username}}\",\n\t\t\t\t\"netconf-password\": \"{{netconf-password}}\"\n\t\t}\n\t},\n\t\"commonHeader\": {\n\t\t\"subRequestId\": \"143748f9-3cd5-4910-81c9-a4601ff2ea58\",\n\t\t\"requestId\": \"e5eb1f1e-3386-435d-b290-d49d8af8db4c\",\n\t\t\"originatorId\": \"SDNC_DG\"\n\t}\n}",
 					"options": {
-						"formdata": {},
 						"raw": {
 							"language": "json"
 						}
@@ -1107,7 +1241,6 @@
 					"mode": "raw",
 					"raw": "{\n\t\"actionIdentifiers\": {\n\t\t\"mode\": \"sync\",\n\t\t\"blueprintName\": \"pnf_netconf\",\n\t\t\"blueprintVersion\": \"1.0.0\",\n\t\t\"actionName\": \"config-deploy\"\n\t},\n\t\"payload\": {\n\t\t\"config-deploy-request\": {\n\t\t\t\"resolution-key\": \"day-2\",\n\t\t\t\t\"pnf-ipv4-address\": \"{{pnf-ipv4-address}}\",\n                \"netconf-username\": \"{{netconf-username}}\",\n\t\t\t\t\"netconf-password\": \"{{netconf-password}}\"\n\t\t}\n\t},\n\t\"commonHeader\": {\n\t\t\"subRequestId\": \"143748f9-3cd5-4910-81c9-a4601ff2ea58\",\n\t\t\"requestId\": \"e5eb1f1e-3386-435d-b290-d49d8af8db4c\",\n\t\t\"originatorId\": \"SDNC_DG\"\n\t}\n}",
 					"options": {
-						"formdata": {},
 						"raw": {
 							"language": "json"
 						}
@@ -1135,7 +1268,6 @@
 		{
 			"listen": "prerequest",
 			"script": {
-				"id": "b3476f00-24ef-4484-af58-525137927dc5",
 				"type": "text/javascript",
 				"exec": [
 					""
@@ -1145,7 +1277,6 @@
 		{
 			"listen": "test",
 			"script": {
-				"id": "4715993f-2476-4d02-a1e3-7f72b9dafeba",
 				"type": "text/javascript",
 				"exec": [
 					""
@@ -1155,30 +1286,24 @@
 	],
 	"variable": [
 		{
-			"id": "a1d2b48e-7c0f-4c95-a476-430be6228e95",
 			"key": "host",
 			"value": "localhost"
 		},
 		{
-			"id": "9202dd75-6852-44fd-b7b0-b8ad0714e8c7",
 			"key": "port",
 			"value": "8081"
 		},
 		{
-			"id": "0087a55c-64f3-44c6-9b56-6300c4b4362e",
 			"key": "pnf-ipv4-address",
 			"value": "127.17.0.2"
 		},
 		{
-			"id": "fd1a7cfe-9526-4261-beb4-61935e8d4ab0",
 			"key": "netconf-username",
 			"value": "netconf"
 		},
 		{
-			"id": "8b004a49-14a3-415e-9646-5c82033bf0ea",
 			"key": "netconf-password",
 			"value": "netconf"
 		}
-	],
-	"protocolProfileBehavior": {}
+	]
 }
\ No newline at end of file
diff --git a/docs/usecases/pnf-simulator.rst b/docs/usecases/pnf-simulator.rst
index 2f6c8472d..83883a241 100644
--- a/docs/usecases/pnf-simulator.rst
+++ b/docs/usecases/pnf-simulator.rst
@@ -3,6 +3,8 @@
 .. International License. http://creativecommons.org/licenses/by/4.0
 .. Copyright (C) 2020 Deutsche Telekom AG.
 
+.. _pnf_simulator_use_case:
+
 PNF Simulator Day-N config-assign/deploy
 ========================================
 
@@ -327,6 +329,8 @@ here but they are not tested by the author of this guide.
          docker ps -a | grep netopeer
 
 
+.. _pnf_simulator_use_case_config_assign_deploy:
+
 Config-assign and config-deploy in CDS
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
diff --git a/docs/userguides/developer-guide/running-bp-processor-in-ide.rst b/docs/userguides/developer-guide/running-bp-processor-in-ide.rst
index ab6ae2314..e31246b01 100644
--- a/docs/userguides/developer-guide/running-bp-processor-in-ide.rst
+++ b/docs/userguides/developer-guide/running-bp-processor-in-ide.rst
@@ -3,6 +3,8 @@
 .. International License. http://creativecommons.org/licenses/by/4.0
 .. Copyright (C) 2020 Deutsche Telekom AG.
 
+.. _running_bp_processor_in_ide:
+
 Running Blueprints Processor Microservice in an IDE
 ====================================================