Migrate Versa Director APIs to Release 23.1

Access the Migration Files

You can access the API migration script from the locations listed in the table below.

To navigate to the tool directories, use the following commands.

• On the Director node:

Administrator@Director01$ cd /opt/versa/vnms/swagger-utils/script/main

• On the local machine (after extracting the tarball):

Administrator@Director01$ cd swagger-scripts/script/main

The table below lists the paths for all migration tool files. 

Prepare API Input

Use the following guidelines to prepare the input for the API migration:

• Use curly braces { } for parameter names in the path. For example, in the path below, SDWAN-Controller1 is the device parameter:
  •  /api/config/devices/device/{SDWAN-Controller1}/config/networks/network path
• Do not include query parameters in the path. For example, in the /vnms/appliance/appliance/liteView?offset=0&limit=25 API path, omit the query parameter part (?offset=0&limit=25) 
• For input options 1 to 3 in Releases 22.1.4 and earlier:
  • Use the exact API path from Swagger/OpenAPI. For example, use /vnms/... , not /rest/vnms/....
  • Provide the path starting with /, not a full https://... URL.
• Use one API path per line in the CSV file.  Duplicate API paths are removed automatically.

API Search Behavior

When the API tool looks up an API in the Swagger specification, it normalizes the input path before matching the path.

For example, for the following API:

/api/config/devices/device/{SDWAN-Controller1}/config/networks/network?offset=0&limit=25

The normalized Swagger input path is:

/config/devices/device/{device}/config/networks/network

In this example:

• In the Swagger API path, the search starts from /config/. The /api prefix is part of the REST base URL, not the Swagger API path.
• Use curly braces { } for parameter names in the path. For example, {SDWAN-Controller1} can be any value and is not matched literally.
• Use the equivalent Swagger path with a path-parameter placeholder (for example, {device} ), not a literal device name.
• The API migration tool ignores the query parameters. The tool strips the question mark (?) and all subsequent query parameters after the question mark (such as ?offset=0&limit=25 in the above example) before the search, and the query parameters are not part of the Swagger API path.

Run the Migration Tool on Versa Director

1. Navigate to the tool directory and run the script.

Administrator@Director01$ cd /opt/versa/vnms/swagger-utils/script/main/
Administrator@Director01$ ./migration_tool.sh

The script starts an interactive menu. Choose one of the following options. For detailed information on each option, see Input Options for Migration Tool, below.

• Migrate APIs from an access log file
• Migrate APIs from a CSV file
• Migrate a single API
• Find Swagger link for a 23.1 API

2. If HTML output is generated using an access log or CSV file, package the generated HTML files into a single archive and copy the archive from Versa Director. See Migrate APIs from an Access Log File (Option 1) and Migrate APIs from a CSV File (Option 2). For example:

Administrator@Director01$ cd ../../
Administrator@Director01$ tar -czvf output.tar.gz output
Administrator@Director01$ mv output.tar.gz /home/Administrator/

3. Download or copy the output.tar.gz file to a machine where you can open it in a browser.
4. Extract the archive and open output/output_swagger.html.

Run the Migration Tool on a Local Machine

To get the local script (swagger-scripts/script/main/migration_tool.sh) to run the migration tool on a local machine, download and extract the api_migration_tool.tar.gz file. If you need support to get the tar file, contact Versa Networks Customer Support team.

1. As a prerequisite, run the following script to verify that the required packages are installed:

Administrator@Director01$ missing=$(for p in jq colordiff python3 python3-pip; do dpkg -s "$p" &>/dev/null || echo "$p"; done; command -v ansi2html &>/dev/null || echo "ansi2html")
if [ -n "$missing" ]; then
echo "Please get the following packages installed first:"
echo "$missing"
else
echo "All required packages are present."
fi

2. Install any packages that are missing. For example:

Administrator@Director01$ sudo apt install jq -y
Administrator@Director01$ sudo apt-get install colordiff
Administrator@Director01$ sudo apt install python3 python3-pip -y
Administrator@Director01$ sudo apt install colorized-logs

3. Download and extract the API migration tool.

Administrator@Director01$ wget <tar file link>
Administrator@Director01$ tar -xvf api_migration_tool.tar.gz

4. Run the API migration tool script.

Administrator@Director01$ cd swagger-scripts/script/main/
Administrator@Director01$ ./migration_tool.sh

The script starts an interactive menu. Choose any one of the following options. For information on what each option requires and step-by-step sample runs, see Input Options for Migration Tool, below.

• Migrate APIs from an access log file
• Migrate APIs from a CSV file
• Migrate a single API
• Find Swagger link for a 23.1 API

5. If HTML output is generated using an access log or CSV file, open the HTML report in any browser at ../../output/output_swagger.html. See Migrate APIs from an Access Log File (Option 1) and Migrate APIs from a CSV File (Option 2).
6. After running the tool on the local machine, remove packages installed in Step 2, above. This step is optional.

Administrator@Director01$ sudo apt remove --purge -y jq colordiff python3-pip colorized-logs
Administrator@Director01$ sudo apt autoremove -y

Migrate APIs from an Access Log File (Option 1)

For Director Releases 22.1.4 or earlier, the access log file is located at /var/log/vnms/spring-boot/access_log.log.

When you use an access log file as input (option 1), respond to the prompts as follows:

• Absolute path of the input access log file—Provide an absolute path to the saved access log file. If you run the script from script/main, you can provide relative paths also (for example: ../../requisite/main/concerto_access_log.log). To use multiple access log files, merge them into a single log file first.
• Current Director version—The supported Director versions are 22.1.3 and 22.1.4. Press Enter to accept the default version, which is 22.1.4.
• Client IP address(s)—The tool displays sample log lines from the access log format to help you identify the correct IP. Copy the client IP address exactly as it appears in the log. To add more than one client IP address, enter each IP address when prompted, and press Enter on an empty line after entering an IP address.
• Swagger IP address—Enter Releases 23.1 and later Director IP address, or press Enter to skip and set the IP address later in the HTML report. See Director IP Address for Swagger Links.

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

Access log file is located at /var/log/vnms/spring-boot/access_log.log on the (<=22.1.4) director

If you wish to give multiple access log files as input, please merge them into a single log file
Please enter the absolute path of the input access log file. (A sample file is located at
../../requisite/main/concerto_access_log.log):
../../requisite/main/concerto_access_log.log

Please enter the current Director version (e.g., 22.1.3 or 22.1.4).
Press Enter to use the default version 22.1.4.

Please enter the IP(s) for the client which is making director API calls.
You will find this IP is access log file. For example : In ../../requisite/main/concerto_access_log.log you can see
'10.192.252.22'

[24/Aug/2024:02:23:17 +0000] 10.192.252.22 - https-jsse-nio-9183-exec-39 ECP_ADMIN cc6ad5df97c0c2dd4dc0ab9030706309 GET
/vnms/spack/predefined?xPath=/predefined/config/predefined-geoip/geoip-countries HTTP/1.1 200 25624 1571ms 1568ms
[24/Aug/2024:02:23:17 +0000] 10.192.252.22 - https-jsse-nio-9183-exec-17 ECP_ADMIN cc6ad5df97c0c2dd4dc0ab9030706309 GET
/vnms/spack/predefined?xPath=/predefined/config/predefined-dlp-data/predefined-threat-severity/threat-severity HTTP/1.1
200 79 42ms 41ms

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 >= 23.1 director for Swagger URL generation. Press Enter if you do not want to input
the director IP:

Please wait while the output is being generated...

Results are generated as an HTML file in ../../output/output_swagger.html.

 Migrate APIs from a CSV File (Option 2)

When you use a CSV file as input (option 2), respond to the prompts as follows:

• Absolute path of the input access log file—Provide an absolute path to the CSV file with one API path per line. If you run the script from script/main, you can provide relative paths also. For example:
  • ../../requisite/main/22.1.4.csv
  • Sample file when running on Director:
    • /opt/versa/vnms/swagger-utils/requisite/main/22.1.4.csv
  • Sample file when running locally:
    • swagger-scripts/requisite/main/22.1.4.csv
• Current Director version—The supported Director versions are 22.1.3 and 22.1.4. Press Enter to accept the default version, which is 22.1.4. After you enter the version, the tool displays API endpoints are being extracted from the CSV file while it processes input.
• Swagger IP address—Enter Releases 23.1 and later Director IP address to get working links immediately, or press Enter to skip and set the IP address later in the HTML report. See Director IP Address for Swagger Links. 

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 absolute path of the input csv file (A sample file is located at ../../requisite/main/22.1.4.csv):
../../requisite/main/22.1.4.csv

Please enter the current Director version (e.g., 22.1.3 or 22.1.4).
Press Enter to use the default version 22.1.4.
22.1.4

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

Please enter the host or IP address of the >= 23.1 director for Swagger URL generation. Press Enter if you do not want to input
the director IP:
10.192.159.23

Please wait while the output is being generated...

Results are generated as an HTML file in ../../output/output_swagger.html.

Migrate a Single API (Option 3)

To migrate a single API (option 3), respond to the prompts as follows:

• There is no Director version prompt for Option 3. Enter the Releases 22.1.4 or earlier API path directly.
• Swagger IP address—Press Enter to skip if you do not have the Releases 23.1 and later Director IP address. The Swagger URL will use the placeholder director-host (for example, https://director-host/swagger-ui/index.html?... ). Replace the director-host placeholder with Releases 23.1 and later Director IP address before opening the link, or re-run and enter the IP address at the prompt. See Director IP Address for Swagger Links, below.
• The Swagger URL is printed without the port :9182. Use the URL as displayed or add the port number :9182 if Director setup requires it.

For this option, results are printed to the console (not to an HTML report).

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-Controller1}/config/networks/network'. SDWAN-Controller1 is device name

Enter a REST API with version <= 22.1.
/api/config/devices/device/{SDWAN-Controller1}/config/networks/network

Please enter the host or IP address of the >= 23.1 director for generation of swagger link. Press Enter if you do not want to
input the director IP:

The>=23.1 REST API is as follows
/api/config/devices/device/{SDWAN-Controller1}/config/networks/network

Swagger URL is as follows:
https://director-host/swagger-ui/index.html?urls.primaryName=network+-+Appliance+Configuration+API

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-Controller1}/config/networks/network'. SDWAN-Controller1 is device name

Enter a REST API with version <= 22.1.
/api/config/system/proxy

Please enter the host or IP address of the >= 23.1 director for generation of swagger link. Press Enter if you do not want to
input the director IP:
10.195.9.11

The>=23.1 REST API is as follows
/vnms/system/proxy

Swagger URL is as follows:
https://10.195.9.11/swagger-ui/index.html?urls.primaryName=Proxy+APIs

Find Swagger Link for a 23.1.1 Version API (Option 4)

Use this option when you already have Releases 23.1 and later API paths and only need the Swagger documentation link. 

To find a Swagger link for a 23.1.1 API (option 3), respond to the prompts as follows:

• There is no Director version prompt and no mapped API output. The tool only prints the Swagger documentation URL and does not perform migration mapping.
• Swagger IP address—Press Enter to skip if needed. The Swagger URL uses the placeholder director-host (for example, https://director-host/swagger-ui/index.html?... ). Replace the director-host in the printed URL with Releases 23.1 and later Director IP address before opening the link, or re-run and enter the IP address at the prompt. See Director IP Address for Swagger Links, below.
• The Swagger URL is printed without the port :9182. Use the URL as displayed or add the port number :9182 if Director setup requires it.

For this option, results are printed to the console (not to an HTML report).

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

Enter a >=23.1 REST API
For example: '/api/config/devices/device/{SDWAN-Controller2}/config/orgs/org-services/{provider-org}/source-ip-guard'
Here, SDWAN-Controller2 and provider-org represent the device and organization names, respectively.
/api/config/devices/device/{SDWAN-Controller2}/config/orgs/org-services/{provider-org}/source-ip-guard

Please enter the host or IP address of the >= 23.1 director for Swagger URL generation. Press Enter if you do not want to input
the director IP:

Swagger URL is as follows:
https://director-host/swagger-ui/index.html?urls.primaryName=source-ip-guard+-+Appliance+Configuration+API

HTML Report

When you use an access log file or CSV file as input (options 1 and 2), the results are generated in an HTML file named output_swagger.html. You can move this file to your local directory and open the file in any browser to view the output. The report provides a clear, tabular view of API migration details between Director Releases 22.1.4 and earlier and Releases 23.1.1 and later.

The following table lists paths to the report when you run the tool on Director or on a local machine. 

The migration tool matches API paths and payloads against its reference data. Incorrect input can produce no match or misleading results. The tool also copies the Appliance_payload_diff.pdf document into the output directory alongside output_swagger.html for appliance payload reference links in the report.

The following table provides descriptions for the columns in the HTML report:

The HTML report includes the following interactive features:

• Update Swagger URLs—If you skipped the Director IP address at the console prompt, use the Enter IP to generate the Swagger URL field at the top of the report. Enter a valid IPv4 address and click Update Link to replace director-host in all Swagger URLs at once. Host names are not accepted by the validator.
• Copy Swagger URL—Click the Copy button next to any Swagger URL to copy to the clipboard.
• Filter APIs—Drop-down values: All, Yes, No, or New (filters on the API Changed column only).
• Exclude API Paths—Hide rows matching comma-separated path fragments (for example, /vnms, /live). Matching is case-insensitive.