Embed Size (px)
Citation preview
Camunda BPMN ASCIIDoctorDocumentation Generator
GeekMustHave
Version 04/04/2018, V2.1p
Table of ContentsSome Design Criteria . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
Bootstrap. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
Initalize NODE. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
GIT the mess . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
ESLint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
ESLint configuration changes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
BPMN/Camunda modules. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
Install ASCIIDoctor markdown . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
Model Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
Camunda Model sample BPMN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
Camunda definitions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
Camunda Collab rootElement. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
Camunda Process rootElement(s) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
Camunda flowElement(s) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
Camunda properties (Extensions) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
Defining pools/lane . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
Camunda ADOC array . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
SVG elelement generation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
ASCIIDcotor formatting. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
Sample Camunda-ADOC process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
Sample Camunda documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
NODE/Javascript CLI interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
Code sample. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
Lessons learned . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
Document History . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
Camunda-Moddle is the library for processing a BPMN file generated byCamunda. ASIIDoctor (ADOC) is the markdown syntax used to document manytechnical documents. The intent is to read a BPMN file and generate an ADOCformatted file with detailed documentation embedded in the BPMN.
These are research notes.
I’m publishing them raw with no editing.
Yes I know, I can’t spell, but I can do math great. I should not have skipped English classes to go tothe Computer Lab. ;-)
There is a PDF version of the document at this link.
There is a HTML Version of this document at this link
Some Design Criteria• The markdown language used is ASCIIDoctor
• Read the BPMN file from Camunda
• Extract list of all BPMN definitions
• Extract definitions
◦ elementID
◦ bpmn:documentation
◦ camunda:property name="order"
◦ camunda:property name="title"
◦ camunda:property name="failure"
◦ camunda:property name="remedy"
◦ Missing Camunda extension properties would be added.
• If possible, Avoid the modeler module with required graphics.
• Simple, standalone, CLI NODE Program
1
Bootstrap
Initalize NODECreate a NODE application package.json
Powershell command to initialize a Node project
npm init
Just hit Enter for all the questions, you can edit this file later.
package.json file
{ "name": "camunda-moddle", "version": "1.0.0", "description": "Can this help ASCIIDoctor experiments?", "main": "index.js", "scripts": { "test": "echo \"Error: no test specified\" && exit 1", "start": "node index.js" ① }, "author": "John Schuster", "license": "MIT"}
① This line was added manually to allow run the code with npm start instead of node index.js
As additional packages are installed (i.e.` npm install chalk`) additional lines will add to thepackage.json file with the dependencies in it.
GIT the messJust about all the development projects, even those that are pet research projects go through tons ifupdates and tests. Use git to have to manage the revisions is essential. You often need to go back toa version that worked.
This project will also be posted on GitHub with all of its mistakes, failures, swearing.
This project is considered open source, remember it’s research and is not necessarily directlyusable by anyone else.
2
Figure 1. Create the local repository.
Figure 2. Stage the files to be committed.
3
Figure 3. Commit the changes
Create a gitignore file
This is critical. It should be done before you push anything to the remote. If you.gitignore a file after it has been pushed it will still be in the history and can beviewed.
Some candidate for being in the gitignore file
• /node_modules - These can be regenerated with npm install.
• gen-doc.ps1 - Has FTP passwords in plain text, yea need to fix that
• files used to create documentation
• .vscode - You Visual code settings for this folder
• .gitignore -No one needs to know what you didn’t push
• .eslintrc.js - ESLint client settings
• Any file with passwords in it
Initial GIT origin publish to remote
The remote repository is at https://github.com/GeekMustHave/Camunda-ASCIIDoc-Generatorwindow="_blank".
git remote add origin https://github.com/GeekMustHave/Camunda-ASCIIDoc-Generator.gitgit push -u origin master
GIT Add Remote
You will need to enter the User ID and Password for the account each time you publish (push). Thisre-entry of credentials can slow things down.
4
Save your credentials for the current project. To make the credentials automatic, you can use theplain text method.
This method will store your credentials in plaintext, not encrypted, which isinsecure.
Remember to add this credentials file (.git-credentials)to the .gitignore file
Run this GIT command first to set up the helper.
GIT credential helper
git config credential.helper store
Then publish the project, you will supply your credentials when asked. VSCode will ask for thecredentials, one last time, and they will be in the .git-credentials file. Every time you publish yourlocal repository, the credentials are obtained from the local .git-credentials file.
These instructions are based on using the Microsoft Visual Code editors' Source Control module.The command may fail if you use them in the Powershell command line.
This section needs updating as the Windows GIT security process is different.
ESLintESLint is an open source JavaScript linting utility created by Nicholas C. Zakas in June 2013. Codelinting is a type of static analysis that is frequently used to find problematic patterns or code thatdoesn’t adhere to certain style guidelines.
JavaScript, being a dynamic and loosely-typed language, is especially prone to developer error.
Without the benefit of a compilation process, JavaScript code is typically executed to find syntax orother errors. Linting tools like ESLint allow developers to discover problems with their JavaScriptcode without executing it.
There is a VSCode plugin for ESLint. Recommend installing it globally
npm install -g eslint
To create the .eslintrc.js configuration file in the project run the following command.
eslint --init
Answer the questions
5
PS F:\myDev\temp\Camunda-documentation-generator> eslint --init? How would you like to configure ESLint? Inspect your JavaScript file(s)? Which file(s), path(s), or glob(s) should be examined? 8? What format do you want your config file to be in? (Use arrow keys)> JavaScript YAML JSONPS F:\myDev\temp\Camunda-documentation-generator> eslint --init? How would you like to configure ESLint? Inspect your JavaScript file(s)? Which file(s), path(s), or glob(s) should be examined?? What format do you want your config file to be in? JavaScript? Are you using ECMAScript 6 features? Yes ①? Are you using ES6 modules? Yes? Where will your code run? Browser? Do you use CommonJS? (y/N)PS F:\myDev\temp\Camunda-documentation-generator> eslint --init? How would you like to configure ESLint? Inspect your JavaScript file(s)? Which file(s), path(s), or glob(s) should be examined?? What format do you want your config file to be in? JavaScript? Are you using ECMAScript 6 features? Yes? Are you using ES6 modules? Yes? Where will your code run? Browser? Do you use CommonJS? No? Do you use JSX? NoDetermining Config: 100% [==============================] 4.2s elapsed, eta 0.0s
Enabled 156 out of 252 rules based on two files.Successfully created the .eslintrc.js file in F:\myDev\temp\Camunda-documentation-generator
① When writing Node CLI applications it is recommended to use Javascript ES6 syntax.
The .eslintrc.js generated was over 250 lines long.
ESLint configuration changes
In the env section these updates were made
"es6": true, // --- Support for node and jQuery "node": true, // --- Allow for require() // "amd":true in env defines require() and define() as global variables as perthe amd spec. // Reference: https://stackoverflow.com/questions/30901417/eslint-how-to-set-eslintrc-to-recognize-require "amd": true
In the rules section, these updates were made
6
// --- Disable "unexpected console" warnings "no-console": "off",
// --- Changed to always // Reference: https://eslint.org/docs/2.0.0/rules/semi "semi": [2, "always"],
BPMN/Camunda modulesInstall the BPMN JavaScript library.
Is this needed or am I confused?
Install BPMN.js Javascript modules
npm install bpmn-js
Install the base BPMN-Moddle first
Install BPMN Moddle modules
npm install bpmn-moddle
Install Camunda BPMN Moddle modules and dependancies.
Install Camaunda BPMN Extension modules
npm install camunda-bmpn-Moddle
After the install, there will be a boatload of new files added to the project.
7
Install ASCIIDoctor markdownThe standard Markdown language has been around forever, and it is used everywhere.
Why use ASCIIDoctor then?
Because it is much more powerful than Markdown without any add-on’s and has a growingfollowing.
There is an excellent video on YouTube (Shameless plug) on how to install it.
https://www.youtube.com/watch?v=0kNOrgTuQsE (YouTube video)
8
Model InformationThe model used in this project example is one I created back six months ago. I have added a fewelements to it to assist in getting some test scenarios.
This model has additional documentation added as BPMN Document and Camunda Properties.
This research uses lots of console.log statements to help use confidence and assistin debugging.
Console.log statements should show the element id not the name, the name is inconsistent anddoesn’t help identify an issue
Camunda Model sample BPMNThe example below is the Camunda SVG file being displayed on the Camunda modeler.
CC
360
Use
r Clicks on Immunization
Link inCC360Start DoneDone
No immunizationfor Beneficiary
Immunization PDF is
Displayed
No Immunization Message for Beneficiary
Done
MD
HH
S
HS
-ES
BM
PI-
AP
IM
CIR
AP
I
Routes response
Verifies CC360 to MPI-
API route
Response:MCIR-IDr
Translates Beneficiary-ID into MCIR-ID
RoutesResponse
Verifies CC360 to MCIR route
Routes Response
Response:PDF Binarydocument
PDF Exist? Response:No PDF for Beneficiary
Response:- No MCIR ID- One MCIR ID- Multiple MCIR ID
Yes
No
MD
HH
S C
C36
0
GET Request
to MPI-API for MCIR ID
Validates User Access to
Beneificary
Message:No
immunization record
More than one Match
GETRequest for MCIR PDF
Using MCIR-ID
Resolve which match
to use????
Prepares PDF response
for viewing
Message:No MCIR PDF
forneficiary
How Many Matches
Response:MCIR Matches
Zero
One or More
Yes
No
Not
es
Version V2.1j03/23/2018
Optum
The link below will provide your a better pan-and-scroll of the SVG file.
This is only available on the web version of the document
Click for Sample.BPMN SVG viewer
This BPMN file can be downloaded from this link.
9
Camunda definitionsThe first layer of the Camunda onion is the definitions.
Base { '$type': 'bpmn:Definitions', id: 'Definitions_1', targetNamespace: 'http://bpmn.io/schema/bpmn', exporter: 'Camunda Modeler', exporterVersion: '1.11.3', rootElements: ① [ Base { '$type': 'bpmn:Collaboration', ② id: 'Collaboration_08t3h7s', documentation: [Array], participants: [Array], messageFlows: [Array] }, Base { '$type': 'bpmn:Process', ③ id: 'Process_1', isExecutable: false, flowElements: [Array] }, Base { '$type': 'bpmn:Process', id: 'Process_1g4sbpp', isExecutable: false, laneSets: [Array], flowElements: [Array], artifacts: [Array] }, Base { '$type': 'bpmn:Process', id: 'Process_0x2rut9', isExecutable: false, flowElements: [Array] }, Base { '$type': 'bpmn:Process', id: 'Process_16c5k76', isExecutable: false, flowElements: [Array] } ], diagrams: [ Base { '$type': 'bpmndi:BPMNDiagram', id: 'BPMNDiagram_1', plane: [Object] } ] }
① RootElements contain major collections of objects
② Collaboration has the Pool and participants
③ This bpmn:Process groups are the pools with collections in them
10
There are a few properties that can be extracted at this level.
// console.log(moddleStuff); console.log("--- the damn ID is:", moddleStuff.id); ① console.log("--- who be da exporter:", moddleStuff.exporter); ②
① --- the damn ID is: Definitions_1
② --- who be da exporter: Camunda Modeler
Camunda Collab rootElement
The first major rootElement under the definition is the single collaboration definitions and list ofParticipants (Each pool name).
11
Base { '$type': 'bpmn:Collaboration', id: 'Collaboration_08t3h7s', documentation: ① [ Base { '$type': 'bpmn:Documentation', text: 'This is the process diagram for the Care Connect 360 to MCIRimmunization interface.' } ], ② participants: ③ [ Base { '$type': 'bpmn:Participant', id: 'Participant_0nf1z3r', name: 'CC360 User' }, ④ Base { '$type': 'bpmn:Participant', id: 'Participant_0ayzoen', name: 'MDHHS' }, Base { '$type': 'bpmn:Participant', id: 'Participant_1n21bza', name: 'MDHHS CC360' }, Base { '$type': 'bpmn:Participant', id: 'Participant_1e29pzo', name: 'Notes' } ], messageFlows: [ Base { '$type': 'bpmn:MessageFlow', id: 'MessageFlow_0s183xi' }, Base { '$type': 'bpmn:MessageFlow', id: 'MessageFlow_00p8nvz' }, Base { '$type': 'bpmn:MessageFlow', id: 'MessageFlow_0lyd8vb' }, Base { '$type': 'bpmn:MessageFlow', id: 'MessageFlow_1bi3hhi' }, Base { '$type': 'bpmn:MessageFlow', id: 'MessageFlow_1mgclp8' }, Base { '$type': 'bpmn:MessageFlow', id: 'MessageFlow_1gs3xu7' }, Base { '$type': 'bpmn:MessageFlow', id: 'MessageFlow_0hbzztz' }, Base { '$type': 'bpmn:MessageFlow', id: 'MessageFlow_0yr99sf' }, Base { '$type': 'bpmn:MessageFlow', id: 'MessageFlow_12zvr61' } ] }
① Collab documentation element, one of these for diagram
② Consider this the diagrams' top level description, there is one of these for the entire diagram.
③ One of these for each pool in the diagram
④ Pools name
Unsure but I think the first RootElement is Collaboration, and the first sub-elementis documentation.
The following code returns the top level documentation
console.log("-- Collab Text--", moddleStuff.rootElements[0].documentation[0].text)
12
returns
-- Collab Text-- This is the process diagram for the Care Connect 360 to MCIRimmunization interface.
The code below will get the participants name (Pool name).
The order of the participants will not necessarily match the order in the diagram.
console.log("-- Participant--", moddleStuff.rootElements[0].participants[0].name);
returns
-- Participant-- CC360 User
13
Camunda Process rootElement(s)
There will be multiple process rootElements for a diagram.
Each process rootElement has a set of flow elements.
Base { '$type': 'bpmn:UserTask', id: 'Task_1yzt5bc', name: 'Clicks on Immunization Link in\nCC360', documentation: [ Base { '$type': 'bpmn:Documentation', text: 'There is a tab on the profile page to obtain the most currentimmunizatiion report for a specific beneficiary.\r\n\r\n\r\n' } ], extensionElements: Base { '$type': 'bpmn:ExtensionElements', values: [ [Object] ] }}
Camunda flowElement(s)
The name of a flow element is defined here
14
The element documentation doesn’t always exist unless the user entered one.
The following code gets the flowElement documentation
15
console.log("-- flowElementDoco --",moddleStuff.rootElements[1].flowElements[0].documentation[0].text)
Which returns
-- flowElementDoco -- There is a tab on the profile page to obtain the most currentimmunization report for a specific beneficiary.
Not all of the flow elements have documentation.
Code to check if a flowElement has a documentation object in it.
if(moddleStuff.rootElements[i].flowElements[j].hasOwnProperty('documentation'))
Camunda properties (Extensions)The power of the project is based on being able to add the documentation directly to the BMPM file.The embedded information should eliminate the sync issues when using external spreadsheets orword documents.
Some property names were selected to help the documentation requirements that currently exist.There is no reason to use just these or these names; you will need to change to code if you do.
Table 1. Camunda properties for the project
PropertyName
Intention for documentation Rules Usage
documentation
Text for more info on this element This is where additional work tasks orreviews needed.
order Any number, suggest starting at 10 andincrement by 10, 10,20,30
Use to help determine the order in whichthe documentation will be printed
title Short text for tooltip When I was headed down the SVGpossible solution, this was going to usethe Tool tip that pop’s up when you hoverover a diagram element
failure Describes what types of failure mightoccur
Any step in a process could fail.
remedy Define the remediation for failures To simply the diagrams
The documentation property is a BPMN property, not a Camunda property
The Camunda extensions are buried in therootElement.flowElements.extensionElements.values.values
The code below shows the optional extensionElements
16
console.log("-- extensionElement --",moddleStuff.rootElements[1].flowElements[0].extensionElements)
which returns, which is closer but, still not there.
Base { '$type': 'bpmn:ExtensionElements', values: [ Base { '$type': 'camunda:Properties', values: [Array] } ] }
Continuing to drill down into the deep dark hole of objects and arrays
console.log("-- extensionElement --",moddleStuff.rootElements[1].flowElements[0].extensionElements.values[0])
which returns the following object
Base { '$type': 'camunda:Properties', values: [ Base { '$type': 'camunda:Property', name: 'order', value: '20' }, Base { '$type': 'camunda:Property', name: 'title', value: 'Click on Immunization link from Patient Summary page' }, Base { '$type': 'camunda:Property', name: 'image', value: 'clientsummary.png' } ] }
Now there is one last level which includes an array of name:value participants
The following code gets to the base of the extended properties.
console.log("-- extensionElement --",moddleStuff.rootElements[1].flowElements[0].extensionElements.values[0].values[0])
which returns
Base { '$type': 'camunda:Property', name: 'order', value: '20' }
17
Defining pools/laneQuestion: How do we get the participants to be in the correct order?
Camunda ADOC arrayThe final result of this process is an array of elements decoded for additional processing.
The object below shows one element a ServiceTask with some Camunda extensions properties in it.
{ "type": "bpmn:ServiceTask", "id": "Task_1b3yiqx", "name": "Verifies \nCC360 to MPI-API route", "doco": "The API gateway verified that CC360 and MPI are allowed to communicate andhow to route the request.", "order": "50", "title": "Gateway routes request to MPI Server", "fail": "Unable to complete onboarding", "remedy": "Call HS-ESB support desk", "i": "2", "j": "1", "k": "3"}
18
Not all elements will have documentation. Here is an element with no documentation
{ "type": "bpmn:ServiceTask", "id": "Task_0qb71ei", "name": "Verifies CC360 to MCIR route", "doco": "", "order": "00", "title": "", "fail": "", "remedy": "", "i": "2", "j": "11", "k": "3"}
The generated ASCIIDoctor file will only have items that have documentation.
the order will determine how they are placed in the generated file.
SVG elelement generationPart of the documentation includes a scalable SVG file for every documented element.
All the generated SVG files can be found in the ./cImages folder.
Each image will be named after it’s ID then SVG prefix, the text tip will be the ID of the elelelemnt.
This is an example of a documented bpmn:ServiceTask element with an ID of Task_0qb71ei.
The generated SVG file would look like
Verifies CC360 to MPI-
API route
ASCIIDcotor formattingASCIIDoctor uses a special syntax to format a table. Below is an example of the format for anASCIIDoctor table.
19
.table description ①[cols="1,4,6,4,4", options="heading"] ②|===| Icon | Name | Doco | Fail | Remedy ③
| image:/cImages/Task_1b3yiqx.svg[Task_1b3yiq] ④| Verifies \nCC360 to MPI-API route| The API gateway verified that CC360 and MPI are allowed to communicate and how toroute the request.| Unable to complete onboarding| Call HS-ESB support desk ⑤
| xxx | yyy | zzz |aaa | bbb ⑥|===<1> formatting reference footer/header for the top of the table<2> Cols= used to size the columns, options= to make the header bolder, moreformatting and setting availabale<3> First row are the headings<4> image:filename.png[description] Example of an embedded image (Generated by thisutility)<5> Exmple of `stacked` columns<6> Example of side by side columns
The generated SVN images are saved in the cImages sub-directory to avoidconfusion with other images in the project.
The resulting table looks like this
Table 2. Diagram definitions
Icon Name Doco Fail Remedy
Verifies CC360 to MPI-
API route
Verifies \nCC360to MPI-API route
The API gateway verifiedthat CC360 and MPI areallowed to communicateand how to route therequest.
Unable tocompleteonboarding
Call HS-ESBsupport desk
xxx yyy zzz aaa bbb
The Name column is a repeat of what is in the content of the SVG image; it could be eliminated tosave space
Table 3. Diagram definitions - No name column
20
Icon Doco Fail Remedy
Verifies CC360 to MPI-
API route
The API gatewayverified that CC360and MPI are allowedto communicate andhow to route therequest."
Unable to complete onboarding Call HS-ESB supportdesk
xxx zzz aaa bbb
The Title was not being shown in previous examples. This example shows the Title spanning threecolumns`
Table 4. Diagram definitions - Title span
Icon Doco Fail Remedy
Verifies CC360 to MPI-
API route
Gateway routes request to MPI Server
The API gatewayverified that CC360and MPI are allowedto communicate andhow to route therequest."
Unable to complete onboarding Call HS-ESB supportdesk
xxx zzz aaa bbb
The image could span across two rows yo make them more viewable.
Table 5. Diagram definitions - Title span / Image Span
Icon Doco Fail Remedy
Verifies CC360 to MPI-
API route
Gateway routes request to MPI Server
The API gatewayverified that CC360and MPI are allowedto communicate andhow to route therequest."
Unable to complete onboarding Call HS-ESB supportdesk
xxx zzz aaa bbb
21
Sample Camunda-ADOC processTo run the Camunda-ADOC generator run the following in a terminal window
npm start
The result will be the following. Logging was turned off in this example.
Sample Camunda documentationTable 6. Diagram definition
TaskType
Description Failure Remedy
(10) Determine Production Deployment Required
UserTask
The Optum team lead working withthe business owner request a newapplication deployment
(20) Please Start Prod RFC Process
SendTask
An message to deploy the applicationis sent to the RFC manager.
There is a standard eMail template forboth regulat and "System Restore" anda "regular" RFC request.
(30) Please Start RFC Prod Process
ReceiveTask
Receipt of this message indicates anew RFC needs to be written.
(40) Creates New RFC with # using RFC System
22
TaskType
Description Failure Remedy
UserTask
The Optum RFC system is used tocollect all informattion for submittingan RFC to SOM-DTMB.
The RFC request must be completedbefore DTMB can be notified yhat aRFC is pending.
(50) Request Type
ExclusiveGateway
A critical RFC request is called a"System Restore". These requests areprocess immediately.
In the process diagram the specialtasks for a "System Restore" will havea background of red.
(60) More than 1 Department?
ExclusiveGateway
A decision is made based on howmany departments are affected by thisRFC.
Multiple department RFCs take moretime (two-week) to deploy.
Single department RFCs can be doneon a Mon-Wed
(70) System Restore RFC
ScriptTask
This RFC involves an immediateprocessing for deployment
This type of RFC is typically for acricial repair where the system is notfunctioning. These RFC are processedimmediately.
The RFC will have a installationwindow of two hours with a start timeentered into the RFC.
RFCs can have a deployment of timeduring the business day if thedeployment will not impair the use ofthe system.
(80) RFC with 2-week notice
23
TaskType
Description Failure Remedy
ScriptTask
This RFC involves more than onedepartment. This type of RFC requiresthat it be filed two weeks befoer thedeployment date.
The RFC will have a installationwindow of two hours with a start timeentered into the RFC.
RFCs can have a deployment of timeduring the business day if thedeployment will not impair the use ofthe system.
(90) RFC with 3-Day Mon-Wed notice
ScriptTask
This RFC involves one department.This type of RFC can be filed on aMOndy with the deployment onWednsday.
The RFC will have a installationwindow of two hours with a start timeentered into the RFC.
RFCs can have a deployment of timeduring the business day if thedeployment will not impair the use ofthe system.
(100) RFC Request Entered
UserTask
The RFC is reviewed and completed.
An RFC may consist of one or twocomponents.
1. Application - The .NET code for theapplication
2. Database - The SQL Server scriptsfor the application.
The RFC will also document whatchanges or repairs will be in thedeployment package.
Optum uses a task tracking systemfrom Atlassian called JIRA. Any JIRAID’s being inluded in the deploymentwill be in the documentation.
(110) Prepare for RFC
24
TaskType
Description Failure Remedy
SendTask
An email request goes to the DTMBgroup informing them of a request toperform a deployment.
(120) Request Auth to deploy
SendTask
An messageis sent to the businessowner to request confirmation for theapplication deployment.
This prevents Optum from publishingupdates that have not been approved.
(130) Assemble Deployment Packages
SendTask
Am email goes to the Optumapplication manager to prepare theapplication package(s) for deployment.
(140) Assemble Deployment Pakage
ReceiveTask
The proper application package(s) willbe identified in the Optum EnterpriseGitHub system and confirmed by thelead developer.
The database script will containautomated package script as well ascustom scripts as needed by thedeployment.
(150) Assemble deployment package with RFC #
UserTask
The deployment package(s) areassembled into ZIP file(s).
There can be one or two ZIP files.
1. Application
2. Database
The packaging process orscript generation fails orgenerates errors.
Cordination between theDeployment managerand the Lead developerresolve any issues.
(160) Assembles package(s) SHA-256 keys
25
TaskType
Description Failure Remedy
ServiceTask
Any of the deployment zip file(s) areprocessed to prepare a SHA-256 keythat follows the ZIP file.
The SHA256 key helps to assure thepackage has not been tampered withand that it is the correct package forthis deployment.
After the SHA256 keys have beengenerated the deployment Zip(s) aretransferred to the SOM SVN server.
Access to the SOM SVN server islimited through use of a SOM securetoken and user autentication.
(170) Package Ready Deploy SHA Keys
SendTask
An email SHA Keys status message issent to the RFC manager and theDTMB Web team.
This message includes the SHA-256keys for each of the package(s).
(174) Update RFC SHA Keys Package Names
UserTask
The SHA-256 key for each of the ZIPfile(s) is added to the RFC to completethe secure package identification.
(200) Request from Optum to Deploy
ReceiveTask
The request for an authorization todeploy application is received.
(210) Verify UAT Completed
UserTask
The business owner is responsible todetermine that the UAT has beencompleted.
Optum typically provides test-casedocumentation to assist theapplication testers.
Some minor application deploymentsor "System Restore" RFCs do notrequire a UAT.
The UAT has not beencompleted or UAT issueshave not been addresses.
The RFC can be held untilthe UAT has beencompleted and any issuesresolved.
(220) You are authorized to deploye
SendTask
A "Authorization to Deploy" messagewill be sent to verify the RFC request.
26
TaskType
Description Failure Remedy
(300) Prepare for an RFC
ReceiveTask
This message indicate there is an RFCbeing files for a productiondeployment.
(310) Process RFC Resolve questions
UserTask
The RFC is validated to assure it iscomplete. A service ticket is writtemfor every department who will assistin the RFC deployment.
The Optum RFC is entered into theDTMB RFC system used by the LCABboards to review and approve all RFCrequests.
(350) Two-Hour SLA
StartEvent
There is a two-hour SLA for a responseto a System Restore RFC
(360) LCAB Director Reveiew
UserTask
System Restore RFC’s are reviewed bytheLCAB Director for immediateprocessing.
Due to somecircumstances a SystemRestore may nor beapproved. The RFC mightconflict with other RFC’sor production Windows.
DTMB, the LCAB Directorand Optum will eitherrework the RFC to allowit to be approved orresumit the RFC at a latertime.
(450) BO Authorized Deployment
ReceiveTask
The "Authorization to Deploy" email isedxported into a PDF format so it canbe added to the RFC.
(540) RFC Deployment Window
StartEvent
The RFC deployment window isestablished in the origibal RFCrequest. DTMB is recommeding two-hour window. This will allow Optumand DTMB to resolve any issues withthe packages.
27
NODE/Javascript CLI interfaceMost CommandLine Interfaces (CLI) are difficult to use. We will use some Node libraries to helpmake the UI better.
One thing is for certain: regarding appearance, the console will never have the sophistication of agraphical user interface. Nevertheless, that doesn’t mean it has to be plain, ugly, monochrome text.You might be surprised by just how much you can do visually, while at the same time keeping itfunctional. We’ll be looking at a couple of libraries for enhancing the display: chalk for colorizingthe output and clui to add some additional visual components. Just for fun, we’ll use figlet to createa fancy ASCII-based banner, and we’ll also use clear to clear the console.
Regarding input and output, the low-level Readline Node.js module could be used to prompt theuser and request input, and in simple cases is more than adequate. But we’re going to takeadvantage of a third-party package which adds a greater degree of sophistication — Inquirer. Aswell as providing a mechanism for asking questions, it also implements simple input controls: thinkradio buttons and checkboxes but in the console.
We’ll also be using minimize to parse command-line arguments.
{tag} Reference: https://www.sitepoint.com/javascript-command-line-interface-cli-node-js/
Here’s a complete list of the packages we’ll use specifically for developing on the command line:
• chalk — colorizes the output
• clear — clears the terminal screen
• clui — draws command-line tables, gauges, and spinners
• figlet — creates ASCII art from text
• inquirer — creates the interactive command-line user interface
• minimist — parses argument options
• configstore — easily loads and saves config without you having to think about where and how.
When I initially installed these package the code of the Camunda Moddle failed. Iadded a list of NODE CLI dependancies from another working project to thisprojects package.json file.
The I ran the npm install which reads those dependencies and gets the node_modules for them.
Code sampleThe code sample came from the GitHub page for this module.
Camunda-BPMN-Moddle link
28
Lessons learnedLessons learned. I have coded for a quite long time. My first programs used punched cards andFortran 4.
I’ve survived all of the shifts in computer technology since then. I force myself to learn the onesthat look promising even if no one else cares.
As a result, I make a lot of mistakes and have "successfully completed failure", on my share ofprojects.
My of the projects I use for reference show the completed professional looking results. As aninstructor, I believe that the mistakes can teach folks too.
I’ve recently moved to the Javascript, Node, Vue, Bootstrap and daily New stuff that appears. I’m notproud or embarrassed by mistakes or failures, and I hope sharing them helps just one person.
Why do I do this?
• I developed a habit early in my career that while I code, I document, all the time.
• It slows me down, but these notes help me to remember why I did that thing in code.
• Some study mentioned that if you write something down, even on a computer, you mightremember it better later.
• It also helps me later, if I become good enough at this, I could teach others.
Case matters
There is a Difference between Bpmmoddle and BPMNModdle
Document Publishing
The process of creating an ASCIIDoctor markdown document which is revision controlled byGIT, remote master and FTP publishing to a website turns out to be quite a few commands. Writea script to help manage this. GEN-Doc.ps1 is the Powershell script I use to be the tool-chain forpublishing ADOC files.
ESLint
Start out using ESLint; it will help you write better code and find code patterns that might causeissues later. It takes a little effort to configure but, it will be worth it.
.gitignore
This file contains the files you don’t want kept in the GIT repository. Add the files you wantexcluded BEFORE you commit or push. Files that are gitignored after a commit or push are stillviewable from the GIT history.
Node dependancies
If you’re going to share your entire project with someone who follows the tl;dr principle thenyou need to use the (--save) option when installing via NPM.
29
Var, Let, Const
Javascript keep evolving as a language. The latest version users let and const rather thaneverything being a var. Const are objects that don’t get modified and let are the objects that thevalue in them changes.
30
ReferencesTable 7. Special marks for items
Attribute name Displays Meaning
{checked} This item has been completed
{tags} A special notable item
{warning} Some to be cautious about
{up} Up vote something
{down} Down vote something
{bookmark} Reference to remember something
{research} Additional review is warented
Document HistoryTable 8. Document History
Date Version Author Description
04/04/18 v2.1p JHRS Documentation adjustments, some spelling
03/27/18 V2.1m JHRS Added better run diagrams
03/26/18 V2.1k JHRS Added the Command Line UI info
03/26/18 V2.1k JHRS Added ESLint and re-posted new repository
03/25/18 V2.1j JHRS complete initial ADOC array generation
03/23/18 V2.1h JHRS Updated the Gen Doc for FTP
03/22/18 V2.1g JHRS Added GIT code the GenDoc PS script
3/20/18 V2.1f JHRS Updated research document to be labeledresearch
03/19/18 V2.1e JHRS Something I can call a beginning
31
