Skip to main content

​
Introduction

Earlier in this learning path, the Automating Workflows and AI Applications lesson introduced nTop’s Command Line Interface (CLI), also known as its headless interface. A Notebook functions as a reusable computational workflow: once its Inputs and Outputs are defined, an external process can provide input values and collect the resulting outputs without requiring manual interaction in nTop.
A diagram showing the process of automating an nTop Notebook using Command Line In this lesson, you will prepare a Notebook for execution outside nTop and run it from the command line. You will also learn how to structure JSON inputs so that a single command can evaluate multiple sets of input values. By the end of this lesson, you will be able to:
  • Prepare a parametric Notebook for headless execution.
  • Run a Notebook from the command line with a single set of inputs.
  • Use JSON to execute a Notebook across multiple sets of inputs.
  • Understand how tools such as Python can further scale and automate these workflows.

​
Requirements and Setup

​
Installation and Access

nTop’s Command Line Interface, nTop Automate, is installed as a separate executable alongside the nTop application. On Windows, the executable is typically located at:
If this directory was added to your system’s PATH during installation, you can run nTop Automate from any directory in PowerShell or Command Prompt by entering ntopcl. Otherwise, you must specify the full path to the executable.
Running the command “ntopcl” will open nTop Automate in Command Line

​
Python Development Environment

If you plan to follow along, download one of the following free software:

​
JSON File Editor

nTop Automate uses JSON files to supply input values to a Notebook and write its output values to a specified file. JSON files are lightweight, text-based files used to store and transport data. They are language-independent, so most programming languages, like Python and C++, can read and write them. To view and edit these files, download Notepad++ or use another text editor that supports JSON formatting. The examples throughout this lesson use Notepad++.

​
Setting up and Running nTop Automate

For the following sections, download and work from the provided nTop File Downloadable Files: Example File Download This file was last updated in nTop 6.03

​
Preparing Your Notebook

A Notebook must have defined Inputs and a single Output before it can communicate with a process outside nTop. This is the same requirement used when packaging a Notebook as a Custom Block. Like a Custom Block, nTop Automate treats the Notebook as a self-contained function: you can supply values designated as Inputs externally, and the value designated as the Output is returned when the workflow finishes executing.
Note: Avoid spaces when naming Notebook files and folders in your working directory. If a file or folder name contains spaces, you must enclose its path in quotation marks when entering commands.

​
Inputs

Convert each variable you want to control during execution into a Notebook Input. You can do this by dragging the variable into the Inputs section at the top of the Notebook or by right-clicking it and selecting Make Notebook Input. Each Notebook Input becomes a parameter that nTop Automate can assign through the command line or an input JSON file.
Dragging variables into the Input section or using the right-click menu are both methods for creating Inputs

​
Output

Because this follows the Custom Block mechanism, a Notebook can have only one declared Output. Drag the block or property you want nTop Automate to return into the Output section, or enter its name directly in the Output field.
Drag a variable into the Output section to define the Output of a Notebook

​
Workflow Validation

Before running the Notebook with nTop Automate, verify that the complete workflow evaluates successfully using the test inputs currently defined in the Notebook.
A complete notebook will not have any unbuilt blocks when all variables are populated (left), while an incomplete notebook will have unbuilt blocks (right) Confirm the following:
  • Every block evaluates successfully, with no unresolved blue question mark (?) icons or error messages. nTop Automate cannot execute a workflow that does not run successfully in the nTop interface.
  • The Notebook filename and working-directory path do not contain spaces. Although spaces are supported when the path is enclosed in quotation marks, avoiding them reduces the likelihood of command-line and scripting errors.

​
Running a Command

There are two ways to provide inputs when executing a Notebook with nTop Automate: directly through the command line or through an input JSON file. JSON is recommended for most workflows because it supports more input types and makes input values easier to identify, modify, and reuse. Entering inputs directly can still be useful for simple workflows and for understanding the structure of an nTop Automate command. To view the available command-line arguments and options, enter the following command in PowerShell or Command Prompt:

​
Method 1: Provide Inputs Through the Command Line

For a simple Notebook, you can enter values directly in the execution command. This method supports only Scalar and Text inputs. Use the -i flag once for each Notebook Input. Values must be provided in the same order in which the Inputs appear in the Notebook:
An example of running an nTop Notebook directly through Command Line with labeled components Include units when they are not already defined by the corresponding Notebook Input. Because the command does not identify which value corresponds to each Input, this method can become difficult to interpret and maintain as the number of Inputs increases. For more complex workflows, use a JSON file to define the input values. This method supports Boolean, Integer, Scalar, Text, File Path, Vector, Point, and Enum input types. Additional information about each type is available in nTop under Documentation → Using nTop Automate → Input. To generate JSON templates for the Notebook, use the -t flag:
Use the -t command to generate a JSON template file for the specified nTop workflow This command generates an input JSON template and an output JSON template in the current working directory. The input template, shown in the image below, contains an entry for each Notebook Input.
The JSON inputs file generated from the -t command above To evaluate more than one value for an Input, change the value property to values and provide the values as a list. For example, the following entry evaluates three values, [2.0, 6.0, 10.0], for the Box Length:
Changing the property “value” to “values” to accept multiple input values After modifying and saving the input JSON file, execute the Notebook with the following command:
An example of running an nTop Notebook using JSON files in Command Line The -j flag specifies the input JSON file, while the -o flag specifies the name of the output JSON file that nTop Automate will create in the working directory. To include additional information about the properties of the Notebook Output, add the -p flag:
Use the -p command for information about the properties

​
Additional Execution and Troubleshooting Options

The following options can help you test, save, and troubleshoot the workflow:
  • Run the command with ntop instead of ntopcl to open the Notebook in the nTop interface with the specified inputs. This allows you to inspect the workflow and confirm that it behaves as intended.
  • Add the -s flag to save the executed Notebook. This overwrites the existing Notebook file.
  • Add -v2 to enable level 2 verbose logging. The default verbosity level is 1, which displays errors and warnings. Level 2 also displays runtime information that can help identify where a workflow is encountering an issue.
  • Add –logfile <LogFile>.txt to save the execution messages to a text file.
Note: In Windows File Explorer, hold Shift, right-click inside the working-directory folder, and select Open PowerShell window here. This opens PowerShell in the correct directory, eliminating the need to navigate there manually.
After the execution finishes, open the generated output JSON file in Notepad++ to review the returned result, such as the calculated Surface Area.
Values for Surface Area based on new values to the Length input.
Note: The values in the image above are printed in meters, while the Surface Area block in the file reports the values in mm

​
Best Practices and Troubleshooting

Before scaling a workflow for automation or integration, verify each stage independently.

​
Verify Your Setup

  1. Confirm that nTop Automate is installed. Run ntopcl without any arguments:
If the nTop Automate command menu appears, the installation is available. If it does not, review the installation and licensing guidance below.
  1. Prepare the nTop Notebook. Configure the required input and output variables according to the recommendations in the Preparing Your Notebook section.
  2. Generate the JSON templates.
  1. Test the workflow with verbose logging. Adding -v2 instructs nTop Automate to display detailed runtime information. Modify the input JSON file with the desired values, and then run:
  1. Verify the results. Open Output JSON file and compare its values with those produced by the same inputs in the nTop GUI. If the results differ or the workflow fails, use the troubleshooting guidance below.

​
Troubleshooting

Example commands and scripts may behave differently depending on the operating environment, licensing configuration, and Notebook setup.

​
Licensing Issues

When using a cloud license, nTop Automate automatically reuses the cached credentials from an active nTop login. If the machine is not already authenticated, credentials can be supplied directly:
A successful authentication attempt should report that the login and logout were successful. If the command does not include a notebook, expect a “No notebook provided” message. For a local license file or floating FlexNet license, use –license and provide either the path to the .lic file or the license server in the format PORT@HOSTNAME.

​
Error Messages and Logging

If an error message does not clearly identify the problem, add -v2 to display detailed runtime information:
Verbose logging helps identify when a failure occurs and which area of the Notebook may be responsible. To save this information for later review, write it to a log file:

​
Input Issues

If an input does not appear to be reaching the Notebook, replace ntopcl with ntop to open the Notebook in the GUI with the specified inputs applied:
This provides a quick way to inspect the input variables and confirm that they load without errors. Alternatively, add -s to save the nTop Automate results and cached inputs in the Notebook for further inspection:

​
Exporting Additional Files

Export blocks write files to the specified directory each time the Notebook executes. Use these blocks when the workflow needs to generate files in addition to returning its declared Notebook Output. For example, combine Text from Scalar with Export Text to write the Notebook Output or other calculated values to a .txt file during each nTop Automate execution. You can also use one or more Concatenate Text blocks with property chips to incorporate relevant input values into exported filenames. This makes it easier to identify files produced by different input configurations. For guidance on converting and combining scalar values as text, refer to this Help Center article. You can use the same approach to construct a complete output path dynamically. Define each level of the folder structure as a separate Notebook Input, and then concatenate those values to create the desired path.
Note: Export blocks, such as Export STL and Export Text, execute during every run regardless of which value is designated as the Notebook Output. Use them for any additional files that should be written to disk with each execution.

​
Scaling nTop Automate Workflows with Python

After completing the five-step validation process outlined in the Best Practices and Troubleshooting section, you can use Python or another scripting language to batch-process the workflow or integrate it with external software. The provided nTop Notebook and Python script will serve as the reference files for this section. The Notebook, BoxPython.ntop, includes an Output File Generation section that demonstrates how Export blocks can generate additional files alongside the declared Notebook Output. For guidance on converting scalar values to text and combining them for filenames or file paths, refer to this Help Center article. Downloadable Files: nTop File Download This file was last updated in nTop 6.03 Python File: BoxExamplePython.py The Python script executes BoxPython.ntop five times through nTop Automate, using a different combination of Length, Width, and Height for each run. For every combination, the script:
  • Creates a numbered subfolder, from run_1 through run_5, within the designated output directory.
  • Writes the input and output JSON files to the corresponding run folder.
  • Executes the Notebook with the specified dimensions.
  • Saves the generated STL and surface-area text file in the same run folder.
  • Prints the command-line output and any errors after each execution.
This structure keeps all files for an individual design iteration together, making results easier to review and compare. Before continuing, place the provided Python script and BoxPython.ntop files in the same working directory. The following procedure builds on the workflow established in the previous sections:
  1. Prepare the nTop Notebook. Define the following values as Notebook Inputs:
  • Length
  • Width
  • Height
  • Output Directory
The Output Directory specifies where the script will create the run folders and save the generated JSON, STL, and text files. Confirm that the Notebook also declares one output for nTop Automate to return.
Note: Replace the sample output-directory path in the provided nTop file with a valid directory on your computer. The existing path is provided only as an example and will not work in your local environment.
The Inputs and Outputs of the example nTop Notebook
  1. Generate the JSON templates. Use the -t flag with nTop Automate to generate the input_template.json and output_template.json files for the Notebook:
Add the -t command to generate the JSON template files
Note: In this example, input_template.json and output_template.json are renamed inputs.json and outputs.json, respectively, as shown in the image below.
The renamed JSON template files
  1. Open and run the Python script. Open your preferred Python code editor and create a .py file for the script that will generate the input JSON files and execute the Notebook with multiple sets of input values. For this example, open the provided .py file and run it from your code editor.
The example Python script open in a code editor If the script executes successfully, it will create five numbered folders in the specified output directory. Each folder will contain the files associated with one design iteration:
  • An STL file of the generated box
  • A text file containing the calculated surface area
  • The input JSON file used for the iteration
  • The output JSON file returned by nTop Automate
A successful script execution will create five numbered folders in the output directory

​
What to Take Away

  • nTop Automate enables headless execution of nTop Notebooks. Once a Notebook has defined Inputs and a single Output, external processes can supply parameters and collect results without manual interaction in nTop.
  • JSON files are the recommended way to supply inputs. They support a wider range of input types, clearly associate values with their parameters, and can be reused for multiple design configurations.
  • Validate the workflow before scaling it. Confirm that the Notebook evaluates successfully in nTop, generate and test its JSON templates, and compare nTop Automate results with those produced in the nTop interface.
  • Logging and diagnostic options simplify troubleshooting. Commands such as -v2, –logfile, and ntop help identify execution errors, inspect applied inputs, and verify workflow behavior.
  • Export blocks can generate additional files during every execution. Use them to write files such as STL and text outputs alongside the Notebook’s single declared Output.
  • Python can scale and integrate nTop Automate workflows. A Python script can automate multiple design iterations, organize and collect their results, and connect nTop workflows with external tools, data sources, simulation software, or broader engineering processes.

​
What’s Next

You have learned the fundamentals of preparing and executing an nTop Notebook for headless automation. Next, test your understanding with a knowledge check.