README.md

   1 Introduction
   2 ============
   3
   4 Workflow Designer is a [pluggable SDC designer](https://wiki.onap.org/display/DW/Generic+Designer+Support) that allows
   5 a user to design a workflow, save it, and attach it to a SDC service as an artifact. Workflow Designer also manages
   6 the definitions of activities, which can be later used as parts of the designed workflows.
   7
   8 Components
   9 ==========
  10
  11 The designer is comprised of the following deployment units:
  12
  13 - Designer backend is the core component. It exposes RESTful APIs for managing workflow and activity data. The backend
  14 is agnostic to the type of a workflow artifact &mdash; its main concerns are workflow inputs and outputs, and metadata.
  15 One of the APIs enables to attach a certified workflow artifact to a SDC service, therefore the designer must be able
  16 to call an API on SDC. In order to do so, the location of a SDC server, and
  17 [SDC consumer](https://wiki.onap.org/display/DW/Consumer+creation) credentials are required.
  18
  19 - Designer frontend serves static content of a Web application for creating and managing workflows, and forwards API
  20 requests to the backend. The static content includes JavaScript, images, CSS, etc. A major part of the Web application
  21 is Workflow Composition View &mdash; a graphical interface for arranging a workflow sequence. The Web application also produces a
  22 workflow artifact that will be sent to the backend, saved along with other data, and later used by a service. The architecture
  23 allows for different implementations of the frontend component. For example, a different technology can be used for the
  24 Composition View, which will probably also result in a different type of the artifacts (e.g. Bpmn.io vs. Camunda).
  25
  26 - Cassandra database is used by the designer backend as the main storage for workflow data. A dedicated instance of
  27 Cassandra can be deployed, or an existing cluster may be used.
  28
  29 - Database initialization scripts run once per deployment to create the necessary Cassandra keyspaces and tables, pre-populate data, etc.
  30
  31 Deployment on Docker
  32 ====================
  33
  34 The procedure below describes manual deployment on plain Docker for development or a demo.
  35
  36 ## 1. Database
  37
  38 Create a dedicated instance of Cassandra. This step is optional if you already have a Cassandra cluster.
  39 The designer is not expected to have problems working with Cassandra 3.x, but has been tested with 2.1.x because this is the version used by
  40 SDC.
  41
  42 An easy way to spin up a Cassandra instance is using a Cassandra Docker image as described in the
  43 [official documentation](https://hub.docker.com/_/cassandra/).
  44
  45 ### Example
  46
  47 `docker run -d --name workflow-cassandra cassandra:2.1`
  48
  49 ## 2. Database Initialization
  50
  51 **WARNING**: *This step must be executed only once.*
  52
  53 `docker run -ti -e CS_HOST=<cassandra-host> -e CS_PORT=<cassandra-port> -e CS_AUTHENTICATE=true/false
  54 -e CS_USER=<cassandra-user> -e CS_PASSWORD=<cassandra-password> nexus3.onap.org:10001/onap/workflow-init:latest`
  55
  56 ### Environment Variables
  57
  58 - CS_HOST &mdash; Cassandra hostname or IP address.
  59
  60 - CS_PORT &mdash; Cassandra Thrift client port. If not specified, the default of 9160 will be used.
  61
  62 - CS_AUTHENTICATE &mdash; whether password authentication must be used to connect to Cassandra. A *false* will be
  63 assumed if this variable is not specified.
  64
  65 - CS_USER &mdash; Cassandra username if CS_AUTHENTICATE is *true*.
  66
  67 - CS_PASSWORD &mdash; Cassandra password if CS_AUTHENTICATE is *true*.
  68
  69 ### Example
  70
  71 Assuming you have created a dedicated Cassandra container as described in Database section, and the access to it is not
  72 protected with a password, the following command will initialize the database:
  73
  74 `docker run -d --name workflow-init
  75 -e CS_HOST=$(docker inspect workflow-cassandra --format={{.NetworkSettings.IPAddress}})
  76 nexus3.onap.org:10001/onap/workflow-init:latest`
  77
  78 ### Troubleshooting
  79
  80 In order to see if the Workflow Designer was successfully initialized, make sure the console does not contain error messages.
  81 You can also see the logs of the initialization container using `docker logs workflow-init` command.
  82
  83 ## 3. Backend
  84
  85 `docker run -d -e SDC_PROTOCL=http/https -e SDC_ENDPOINT=<sdc-host>:<sdc-port> -e SDC_USER=<sdc-username>
  86 -e SDC_PASSWORD=<sdc-password> -e CS_HOSTS=<cassandra-hosts> -e CS_PORT=<cassandra-port>
  87 -e CS_AUTHENTICATE=true/false -e CS_USER=<cassandra-user> -e CS_PASSWORD=<cassandra-password>
  88 -e JAVA_OPTIONS=<jvm-options> -e SHOW_HEALTH=<heathcheck-mode> nexus3.onap.org:10001/onap/workflow-backend:latest`
  89
  90 ### Environment Variables
  91
  92 - SDC_PROTOCOL &mdash; protocol to be used for calling SDC APIs (http or https).
  93
  94 - SDC_ENDPOINT &mdash; the base path of SDC external API, in the format  ="10.247.41.20:8080"
  95
  96 - SDC_USER &mdash; Workflow consumer username
  97
  98 - SDC_PASSWORD &mdash; Workflow consumer password
  99
 100 - CS_HOSTS &mdash; comma-separated list of Cassandra hostnames or IP addresses.
 101
 102 - CS_PORT &mdash; CQL native client port. If not specified, the default of 9042 will be used.
 103
 104 - CS_AUTHENTICATE &mdash; whether password authentication must be used to connect to Cassandra. A *false* will be
 105 assumed if this variable is not specified.
 106
 107 - CS_USER &mdash; Cassandra username if CS_AUTHENTICATE is *true*.
 108
 109 - CS_PASSWORD &mdash; Cassandra password if CS_AUTHENTICATE is *true*.
 110
 111 - JAVA_OPTIONS &mdash; optionally, JVM (Java Virtual Machine) arguments.
 112
 113 - SHOW_HEALTH &mdash; how health information will be exposed, as documented in
 114 [Spring Boot](https://docs.spring.io/spring-boot/docs/current/reference/html/production-ready-endpoints.html#production-ready-health) documentation.
 115 The default for Workflow designer is *always*.
 116
 117 ### Example
 118
 119 Assuming you have a dedicated Cassandra container as described in Database section, and the access to it is not
 120 protected with a password. The following command will start a backend container:
 121
 122 `docker run -d --name workflow-backend -e SDC_PROTOCOL=http
 123 -e SDC_ENDPOINT=$(docker inspect sdc-BE --format={{.NetworkSettings.IPAddress}}):8080
 124 -e CS_HOSTS=$(docker inspect workflow-cassandra --format={{.NetworkSettings.IPAddress}})
 125 -e SDC_USER=workflow -e SDC_PASSWORD=<secret> -e JAVA_OPTIONS="-Xmx128m -Xms128m -Xss1m"
 126 nexus3.onap.org:10001/onap/workflow-backend:latest`
 127
 128 ### Troubleshooting
 129
 130 In order to verify that the Workflow Designer backend has started successfully, check the logs of the
 131 backend container. For example, by running `docker logs workflow-backend`. The logs must not contain any
 132 error messages.
 133
 134 Application logs are located in the */var/log/ONAP/workflow-designer/backend* directory of a workflow backend
 135 container. For example, you can view the audit log by running
 136 `docker exec -ti workflow-backend less /var/log/ONAP/workflow-designer/backend/audit.log`.
 137
 138 ## 4. Frontend
 139
 140 `docker run -d -e BACKEND=http://<backend-host>:<backend-port> -e JAVA_OPTIONS=<jvm-options>
 141 nexus3.onap.org:10001/onap/workflow-frontend:latest`
 142
 143 - BACKEND &mdash; root endpoint of the RESTful APIs exposed by a workflow backend server.
 144
 145 - JAVA_OPTIONS &mdash; optionally, JVM (Java Virtual Machine) arguments.
 146
 147 ### Example
 148
 149 `docker run -d --name workflow-frontend
 150 -e BACKEND=http://$(docker inspect workflow-backend --format={{.NetworkSettings.IPAddress}}):8080
 151 -e JAVA_OPTIONS="-Xmx64m -Xms64m -Xss1m" -p 9088:8080 nexus3.onap.org:10001/onap/workflow-frontend:latest`
 152
 153 Notice that port 8080 of the frontend container has been
 154 [mapped]( https://docs.docker.com/config/containers/container-networking/#published-ports) to port 9088 of the host
 155 machine. This makes the Workflow Designer Web application accessible from the outside world via the host machine's
 156 IP address/hostname.
 157
 158 ### Troubleshooting
 159
 160 In order to check if the Workflow Designer frontend has successfully started, look at the logs of the
 161 frontend container. For example, by running `docker logs workflow-frontend`. The logs should not contain
 162 error messages.
 163
 164 Workflow frontend does not have backend logic, therefore there are no application logs.
 165
 166 SDC Plugin Configuration
 167 ========================
 168
 169 In order to run as an SDC pluggable designer, Workflow Designer must be added to SDC configuration as described in
 170 [Generic plugin support](https://wiki.onap.org/display/DW/Generic+Designer+Support).
 171
 172 If you are deploying SDC using a standard procedure (OOM or the
 173 [SDC shell script](https://wiki.onap.org/display/DW/Deploying+SDC+on+a+Linux+VM+for+Development)),
 174 the easiest way to configure the Workflow plugin is to edit the *default_attributes/Plugins/WORKFLOW*
 175 section of *AUTO.json*.
 176
 177 ### Plugin Source
 178
 179 The main endpoint to load Workflow Designer Web application is defined by `"pluginSourceUrl": "http://<host>:<port>"`.
 180
 181 Keep in mind that the URL **must be accessible from a user's browser**. In most cases, `<host>` will be the hostname or
 182 IP address of the machine that runs Docker engine, and `<port>` will be a host port to which you have published port
 183 8080 of the Workflow frontend container.
 184
 185 ### Plugin Discovery
 186
 187 In order to check the availability of a plugin, SDC uses `"pluginDiscoveryUrl"`. For Workflow the value is
 188 `http://<host>:<port>/ping`.
 189
 190 ### Example
 191
 192 Let's assume that hostname of the machine that runs Docker containers with the Workflow application is
 193 *workflow.example.com*, and port 8080 of the Workflow frontend is mapped to 9088 on the host. In this case the corresponding
 194 section of *AUTO.json* will look like below:
 195
 196 ```
 197 "Plugins": {
 198     "WORKFLOW": {
 199         "workflow_discovery_url": "http://workflow.example.com:9088/ping",
 200         "workflow_source_url": "http://workflow.example.com:9088"
 201     }
 202 },
 203 ```