Merge "CDS API Reference add workflow tutorial"

1 files changed, 97 insertions, 1 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