vRODoc – Convert vRO Actions to JSDoc Pages

Introduction

It’s always been hard to find a way to document vRO Workflows whether working on large VMware Automation environments or be it your personal projects. I was quite anxious about it as well and tried to find some easy way to do it.

Then, one day I found a PS script by Jose Cavalheri & Michael Van de gaer where they were trying to get JS actions and configuration elements out of an unzipped vRO Package. It was quite helpful and I used it as a building block for my project that I will be talking about today. I also used export-package mechanism by Burke Azbill and some bits of vROIDE by Garry Hughes.

So before we start, let me tell you that if you want to make this functionality to work in your project, you should think of moving your code to vRO actions as much as possible.

vRO Actions are much more flexible in terms of their usage outside of vRO. As you might know, vRO uses XML based approach to save both workflows and actions. However, due to the varied nature of workflows that can contain almost anything in any format makes them convoluted. Actions on the other hand, not only have a defined scope (takes inputs and return one output) but also much easier to use in vRO as well as they provide code reusability. I know, Not everything in vRO can be and should be converted to vRO actions BUT THAT’S OK. We can deal with it. I would recommend to move to action based approach for anyone working on vRO.

Ultimately, Our objective is to document most of our code and custom APIs that we have created in form of actions.

What is vRODoc?

It is mostly a PowerShell script that connects with your vRealize Orchestrator to fetch a package that contains all your action modules and action items, intelligently add JSDoc annotation to those action items and convert them into html pages which can be presented as a web-based code documentation. See a live example here. You can also add other JSDoc comments to your actions. Learn more about JSDoc comments here.

How to get started?

Please understand this flow to get started.

Steps to follow

A Quick demo on how to create a Github Pages based website that documents all your vRO actions.

Create a package in vRO which will be used to fetch the code-to-be-documented.
Using REST, add action modules to your package using this API

Download vRODoc from here and Extract it to get the vrodoc_script.ps1 file
or just run

PS> Install-Script -Name vRODoc

Edit local copy of your vrodoc_script.ps1 to set your environment parameters

Execute this ps1 file. It may take few minutes depending on package size.
In your export path, you will notice 1 .zip file and 1 folder with your package-name.

Inside package folder, a folder “Actions” will be created with all the converted JSDoc annotated vRO Actions.

By now, you have successfully created your website. Inside package folder, go to docs folder and open index.html

Now, its time to push the content of docs folder to your repository (can be Github.com, Gitlab .com or Gitlab Self-Hosted) – I will take example of Github.com

Assuming the repo already exists in your github account, push it to your repo

Go to Settings > Pages and select Branch: main and folder/: docs and wait for few minutes for website to load on Github Pages

Bingo! Your vRO custom API documentation is live and ready for your team. See test deployment at https://imtrinity94.github.io/com.test.module/

If you reading this line, I hope you like this article. This whole process executes from a Powershell script that can be scheduled nightly or something on one of your machine to see the latest documentation next day.

Future Scope

I am also working on making it executable from Github or Gitlab runners. That could be tricky and highly environment specific but will give it a try soon. Stay tuned.