Migrate Versa Director APIs to Release 23.1

Input Options for APIs with Version 22.1 or Lower

Enter your current Director version when prompted in the console. Ensure that you input only the supported versions listed in the console (applicable only for options 1 and 2 below).

You can provide API inputs in one of the four ways:

1. Access Log File

   Save the access log file containing API calls with version 22.1 or lower anywhere in your system.

   When the script prompts for the input access log file name, enter the absolute path of the saved log file.
   Afterward, you will be asked to provide the following:

   Exclusion List: Enter an IP address or a list of IP addresses whose API calls you want to exclude from the output.
   Inclusion List: Enter an IP address or a list of IP addresses whose API calls you want to include in the output.

   Output: An HTML file named output_swagger.html is generated and saved in the /opt/versa/vnms/swagger-utils/output directory. You can move this file to your local, open this file in any browser to view the output.

2. CSV File

   Save the csv file containing multiple APIs with version 22.1 or lower anywhere in your system.

   When the script prompts for the csv file name, enter the absolute path of the saved csv file.

   Output: An HTML file named output_swagger.html is generated and saved in the /opt/versa/vnms/swagger-utils/output directory. You can move this file to your local, open this file in any browser to view the output.

3. Single <= 22.1 API
   
   Instead of an access log file, you can directly input a single API call with version 22.1 or lower when prompted by the script during execution.
   
   Output: The output (>= 23.1 API and Swagger URL) is displayed directly on the console.

4. Single >= 23.1 API

   You can directly input a single API call with version 23.1 or higher when prompted by the script during execution
   
   Output: The output(Swagger URL) is displayed directly on the console.

Examples

Navigate to the /opt/versa/vnms/swagger-utils/script/main directory to execute the script.

• Example 1: When input format is given as an access log file.

/opt/versa/vnms/swagger-utils/script/main $ ./migration_tool.sh
This shell script is responsible for generating the API >= 23.1 along with the corresponding Swagger URL and payload changes.

Input:
Access log file containing <= 22.1 APIs, csv file containing <= 22.1 APIs, a single <= 22.1 API or a single >= 23.1 API
Output:
>= 23.1 APIs along with the corresponding Swagger URLs and payload changes.
       - An HTML page is generated when a log file or a csv file is provided.
       - Output is displayed on the console when a single API is provided.
==========================================================================
Enter an Option:

1. Enter 1 if you want to provide input as an access log file.
2. Enter 2 if you want to provide input as a csv file containing multiple <=22.1 APIs.
3. Enter 3 if you want to provide input as a single <= 22.1 API.
4. Enter 4 if you want to provide input as a single >= 23.1 API to generate swagger link in console.

Enter your choice(1, 2, 3 or 4)
1
Please enter the input log file name (A sample file is located at /opt/versa/vnms/swagger-utils/requisite/main/concerto_access_log.log):
concerto_access_log.log

Please enter the current version of your director(22.1.3, 22.1.4)
22.1.4

Please enter the IPs for exclusion list:
Enter IP address, or press enter if there are no more IPs to enter:
10.192.252.15
Enter IP address, or press enter if there are no more IPs to enter:

Please enter the list of IPs for the inclusion list by including the tool IP that makes the API calls
Enter IP address, or type enter if there are no more IPs to enter:
10.192.252.22
Enter IP address, or type enter if there are no more IPs to enter:

API endpoints are being extracted from access logs....

Please enter the host or IP address of the director. Press Enter if you do not want to input the director IP:
10.195.9.11
Please wait while the output is being generated...

Results are generated as an HTML file in /opt/versa/vnms/swagger-utils/output/output_swagger.html.

• Example 2: When input is given as a csv file containing multiple <=22.1 APIs.

/opt/versa/vnms/swagger-utils/script/main $ ./migration_tool.sh
This shell script is responsible for generating the API >= 23.1 along with the corresponding Swagger URL and payload changes.

Input:
Access log file containing <= 22.1 APIs, csv file containing <= 22.1 APIs, a single <= 22.1 API or a single >= 23.1 API

Output:
>= 23.1 APIs along with the corresponding Swagger URLs and payload changes.
    - An HTML page is generated when a log file is provided.
    - Output is displayed on the console when a single API is provided.
==========================================================================
Enter an Option:

1. Enter 1 if you want to provide input as an access log file.
2. Enter 2 if you want to provide input as a csv file containing multiple <=22.1 APIs.
3. Enter 3 if you want to provide input as a single <= 22.1 API.
4. Enter 4 if you want to provide input as a single >= 23.1 API to generate swagger link in console.

Enter your choice(1, 2, 3 or 4)
2
NOTE:
Use angle brackets '{ }' to define parameter names when specifying the API in the CSV file or on the console.

For example: '/api/config/devices/device/{SDWAN-Controller2}/config/orgs/org-services/{provider-org}'
Here, SDWAN-Controller2 and provider-org represent the device and organization names, respectively.

Please enter the input file name (A sample file is located at swagger-scripts/requisite/main/ncs_api.csv):
ncs_api.csv

Please enter the current version of your director(22.1.3, 22.1.4)
22.1.4

API endpoints are being extracted from the csv file...

Please enter the host or IP address of the director. Press Enter if you do not want to input the director IP:
10.195.9.11
Please wait while the output is being generated...

Results are generated as an HTML file in /opt/versa/vnms/swagger-utils/output/output_swagger.html.

Example 3: When input is given as a single <=22.1 API.

This shell script is responsible for generating the API >= 23.1 along with the corresponding Swagger URL and payload changes.

Input:
Access log file containing APIs with <= 22.1, csv file containing <= 22.1 APIs, a single <= 22.1 API or a single >= 23.1 API
Output:
>= 23.1 APIs along with the corresponding Swagger URLs and payload changes.
    - An HTML page is generated when a log file or csv is provided.
    - Output is displayed on the console when a single API is provided.
==========================================================================
Enter an Option:

1. Enter 1 if you want to provide input as an access log file.
2. Enter 2 if you want to provide input as a csv file containing multiple <=22.1 APIs.
3. Enter 3 if you want to provide input as a single <= 22.1 API.
4. Enter 4 if you want to provide input as a single >= 23.1 API to generate swagger link in console.

Enter your choice(1, 2, 3 or 4)
3

NOTE : Give param names inside angle bracket '<>' while defining the API inside the csv file or console.
For example '/api/config/devices/device/<SDWAN-Controller2>/config/orgs/org-services/<provider-org>'. SDWAN-Controller2 and provider-org are device and org name respectivily

Enter a REST API with version <= 22.1.
/api/config/devices/template/VD-Tenant-1-QTSBLR-DataStore/config/orgs/org/VD-Tenant-1-QTSBLR/available-networks?select=name

Please enter the host or IP address of the director. Press Enter if you do not want to input the director IP:
10.195.9.11
Please wait while the output is being generated...

The >=23.1 REST API is as follows
/api/config/devices/template/VD-Tenant-1-QTSBLR-DataStore/config/orgs/org/VD-Tenant-1-QTSBLR/available-networks?select=name

Swagger URL is as follows:
https://10.195.9.11:9182/swagger-ui/index.html?urls.primaryName=security - Appliance API

Example 4: When input is given as a single >=23.1 API.

This shell script is responsible for generating the API >= 23.1 along with the corresponding Swagger URL and payload changes.

Input:
Access log file containing APIs with <= 22.1, csv file containing <= 22.1 APIs, a single <= 22.1 API or a single >= 23.1 API
Output:
>= 23.1 APIs along with the corresponding Swagger URLs and payload changes.
    - An HTML page is generated when a log file or csv file is provided.
    - Output is displayed on the console when a single API is provided.
==========================================================================
Enter an Option:

1. Enter 1 if you want to provide input as an access log file.
2. Enter 2 if you want to provide input as a csv file containing multiple <=22.1 APIs.
3. Enter 3 if you want to provide input as a single <= 22.1 API.
4. Enter 4 if you want to provide input as a single >= 23.1 API to generate swagger link in console.

Enter your choice(1, 2, 3 or 4)
4

Enter a >=23.1 REST API
/nextgen/organization/uuid/{uuid}

Please enter the director IP
10.195.9.10

Swagger URL is as follows:
https://10.195.9.10:9182/swagger-ui/index.html?urls.primaryName=Organization API

• Additional steps to follow while running the tool in local:
  
  Requirements: (Only needed when the tool is run locally)
  
  Before running the tool, please ensure the following packages are installed by running these commands:

sudo apt update
sudo apt-get install colordiff
sudo apt install colorized-logs
sudo apt install jq
sudo apt install maven