Ansys Dynamic Reporting CLI Utility#
A command line utility is included that allows for many Ansys Dynamic Reporting operations to be run from the command line. These operations include: listing entities on the server, importing entities from files on disk, deleting entities, copy entities between servers and modify the tags on entities. These functions are implemented as a single command line tool, leveraging sub-commands to perform the individual operations.
Basic Command Usage#
adr [-h] {cp,htmlexport,pdfexport,import,ls,rm,tag} ...
The sub-commands are:
Help on individual commands may be obtained by combining -h with the sub-command, so:
adr cp -h
will display help related to the sub-command.
Note
Most commands require the URL of a server to be provided. This is usually in the form: http://{username}:{password}@hostname:{port}. For example: http://nexus:cei@127.0.0.1:8000. This URL syntax exposes the username and password of the database in cleartext as such command lines are often visible to all users running on the same system. If no username or password is supplied (e.g. http://127.0.0.1:8000), the tool will look at the environmental variables: ADR_TOOLS_USERNAME and ADR_TOOLS_PASSWORD for the username and password to use, avoiding command line exposure.
For templates, generally only top level templates can be manipulated for operations like deleting and copying and those operations will be applied to the entire tree of templates.
Copy Sub-command (cp)#
usage: adr.bat cp [-h] [--test] [--verbose] [--type {item,template}] [--query query_string]
source_server_url destination_server_url
Copy items, sessions, datasets and templates from one ADR server to another.
positional arguments:
source_server_url ADR server URL. Example: http://nexus:cei@127.0.0.1:8000
destination_server_url
Target ADR server URL. Example: http://nexus:cei@127.0.0.1:8000
options:
-h, --help show this help message and exit
--test Validate the operation, but do not perform it
--verbose Include progress and other information
--type {item,template}
Select the object type to copy. Default: item
--query query_string Specify a query string. Default: no filter
Description#
This tool copies a selected collection of objects (data items or templates) from one server to another. GUIDs are preserved and any referenced session and dataset objects are copied as well.
Arguments#
source_server_url This argument specifies the hostname, port, username and password of the ADR server to read items from. For example: http://nexus:cei@127.0.0.1:8000 specifies a server running on the local machine (127.0.0.1) on port 8000. The username is 'nexus' and the password is 'cei'.
destination_server_url This argument specifies the hostname, port, username and password of the ADR server to copy items into. For example: http://nexus:cei@127.0.0.1:8000 specifies a server running on the local machine (127.0.0.1) on port 8000. The username is 'nexus' and the password is 'cei'.
Options#
Various options exist.
-h, --help Show the usage message and exit
--verbose Display additional status and progress information during the operation.
--test Causes the tool to simulate the operation without actually performing it. This is helpful when debugging command lines, especially when used in conjunction with the -verbose option.
--type {item,template} Specify the type of objects to copy. This command can copy data items or templates.
--query query_string Use the specified query string to select the specific objects of the specified type (--type option) to perform the operation on. The syntax is documented here.
Import Sub-command (import)#
usage: adr.bat import [-h] [--disable_encoding_check] [--session_guid [session_guid]] [--session_date [date]]
[--session_hostname [hostname]] [--session_platform [platform]]
[--session_application [application]] [--session_version [version]] [--session_tags [tag_string]]
[--dataset_guid [dataset_guid]] [--dataset_filename [filename]] [--dataset_dirname [directory]]
[--dataset_format [format]] [--dataset_parts [count]] [--dataset_elements [count]]
[--dataset_tags [tag_string]] [--data_guid [item_guid]] [--data_date [date]]
[--data_sequence [number]] [--data_name [name]] [--data_source [name]] [--data_tags [tag_string]]
[--data_categories [categoryA [categoryB ...]]] [--ext_image [ext ...]] [--ext_movie [ext ...]]
[--ext_table [ext ...]] [--ext_scene [ext ...]] [--ext_file [ext ...]] [--ext_text [ext ...]]
[--ext_html [ext ...]] [--table_col_labels] [--table_row_labels] [--table_numeric]
[--table_delimiter [char]] [--table_quote_char [char]] [--verbose] [--test] [--print_options]
adr_server_url [file|directory ...]
Import data items from disk into the ADR server.
positional arguments:
adr_server_url ADR server URL. Example: http://nexus:cei@127.0.0.1:8000
file|directory File and directory names to import
options:
-h, --help show this help message and exit
--disable_encoding_check
Disable the implicit check for UTF-8 encoding of uploaded files
--session_guid [session_guid]
GUID of an existing Ansys Dynamic Reporting session to use for new data items
--session_date [date]
Creation date for the created session
--session_hostname [hostname]
Hostname for the created session
--session_platform [platform]
Platform name for the created session
--session_application [application]
Application name for the created session
--session_version [version]
Version for the created session
--session_tags [tag_string]
Tags for the created session
--dataset_guid [dataset_guid]
GUID of an existing Ansys Dynamic Reporting dataset to use for new data items
--dataset_filename [filename]
Filename for the created dataset
--dataset_dirname [directory]
Directory name for the created dataset
--dataset_format [format]
Format for the created dataset
--dataset_parts [count]
Number of parts for the created dataset
--dataset_elements [count]
Number of elements for the created dataset
--dataset_tags [tag_string]
Tags for the created dataset
--data_guid [item_guid]
GUID for newly imported items (note only useful when importing a single data item, use with caution)
--data_date [date] Creation date for created data items (__timestamp__ is the file timestamp)
--data_sequence [number]
Sequence number for the created data items
--data_name [name] Name for created data items (__file__ is the file basename)
--data_source [name] Source for created data items (__file__ is the file basename)
--data_tags [tag_string]
Tags for created data items
--data_categories [categoryA [categoryB ...]]
List of space-separated categories to assign the item to.
--ext_image [ext ...]
Filename extensions to be imported as image. Default: ['png', 'jpg']
--ext_movie [ext ...]
Filename extensions to be imported as movie. Default: ['mp4']
--ext_table [ext ...]
Filename extensions to be imported as table. Default: ['csv']
--ext_scene [ext ...]
Filename extensions to be imported as scene. Default: ['stl', 'ply', 'csf', 'avz', 'scdoc', 'dsco']
--ext_file [ext ...] Filename extensions to be imported as file. Default: []
--ext_text [ext ...] Filename extensions to be imported as text. Default: ['txt']
--ext_html [ext ...] Filename extensions to be imported as html. Default: ['htm', 'html']
--table_col_labels Input csv files will have a column label row
--table_row_labels Input csv files will have a row label column
--table_numeric Table items generated from .csv files will have strictly numeric content
--table_delimiter [char]
The delimiter in csv files
--table_quote_char [char]
The quote character in csv files
--verbose Enable verbose mode
--test Validate the operation, but do not perform it
--print_options Print import configuration option values
Description#
The tool allows a user to upload data from files into an Ansys Dynamic Reporting database. This is similar to the "Upload files into data items" application in the Ansys Dynamic Reporting web interface. In addition to specifying files or directories to upload, many options for defining exactly how the data should be incorporated into the existing data at the ADR server are provided. These include specification of session, dataset, tags, what data item type-specific file extensions should be uploaded as, and how tables should be handled.
Item file uploads for files of type 'csv, txt and html' now have to be strictly UTF-8 encoded. On upload, there is a check for UTF-8 encoding which is used to force this requirement. This check is enabled by default and uploads will fail if this check fails. You can disable this check using -disable_encoding_check if you feel that your file is correctly encoded.
The tool takes a list of files and/or directories as arguments. When a directory is specified, the tool will recursively visit its contents, uploading all files that match the file extensions specified with the -ext_* options.
Arguments#
adr_server_url This argument specifies the hostname, port, username and password of the ADR server to import the data items into. For example: http://nexus:cei@127.0.0.1:8000 specifies a server running on the local machine (127.0.0.1) on port 8000. The username is 'nexus' and the password is 'cei'.
file | directory ... This argument specifies the name of a specific file to import or the name of a directory whose files should be imported. This argument may be repeats as needed. Note: the tool will recurse into the directory, looking for files with the matching extensions to import.
Options#
If any of these options are specified multiple times on the command line, only the last one takes effect.
-h, --help Show the usage message and exit
--session_guid [GUID] The Globally Unique IDentifier (GUID) of the session to associated the data with. If omitted, a new session is created and assigned a new GUID. This new session GUID is then associated with the data. The additional -session_* command-line options are provided to specify attributes of the new session.
--session_date [date] The creation date for the created session. This option is ignored if an existing session GUID is used instead of creating a new session. If omitted, the current time stamp is used. The format of the date is that parsed by the Python dateutil.parser.parse method, which is able to parse most known formats.
--session_hostname [hostname] The host name to associate with the created session. This option is ignored if an existing session GUID is specified. The default is the host name of the system the tool is run on.
--session_platform [platform] The platform (operating system) name to associate with the created session. This option is ignored if an existing session GUID is specified. The default is the platform of the system the tool is run on.
--session_application [application] The application name to associate with the created session. This option is ignored if an existing session GUID is specified. The default is "adr_data_import".
--session_version [version] The version to associate with the created session. This option is ignored if an existing session GUID is specified. The default is the version number of the tool.
--session_tags [tag string] A space-separated list of tags to associate with the created session. This option is ignored if an existing session GUID is specified. The default is empty (no session tags). Note that session tags, dataset tags, and data item tags are distinct and separate. It's a common mistake to specify -session_tags when -data_tags is intended.
--dataset_guid [GUID] The GUID of the dataset to associate the data with. If omitted, a new dataset is created and assigned a new GUID. This new dataset GUID is then associated with the data. The additional -dataset_* command-line options are provided to specify attributes of the new dataset.
--dataset_filename [file name] The file name for the created dataset. This option is ignored if an existing dataset GUID is specified. The default file name is "unspecified".
--dataset_dirname [directory name] The directory name for the created dataset. This option is ignored if an existing dataset GUID is specified. The default directory name is the current working directory when the adr_data_import tool was run.
--dataset_format [format] The format for the created dataset as a string. This option is ignored if an existing dataset GUID is specified. The default format string is "unspecified".
--dataset_parts [count] The number of parts in the created dataset. This is only useful when 3D scene data is imported. This option is ignored if an existing dataset GUID is specified. The default is 0.
--dataset_elements [count] The number of elements in the created dataset. This is only useful when 3D scene data is imported. This option is ignored if an existing dataset GUID is specified. The default is 0.
--dataset_tags [tag string] A space-separated list of tags to associate with the created dataset. This option is ignored if an existing dataset GUID is specified. The default is empty (no dataset tags). Note that session tags, dataset tags, and data item tags are distinct and separate. It's a common mistake to specify -dataset_tags when -data_tags is intended.
--data_date [date] The creation date for the created data items. The format of the date is that parsed by the Python dateutil.parser.parse method, which is able to parse most known formats. If the string "__timestamp__" is specified for the date, the creation date used will be that of each data file. The default is now, the time when the tool was run.
--data_sequence [sequence number] The sequence number for the created data items. This is used if data items can be considered in a specific ordered sequence. The default sequence number is 0.
--data_name [name] The name for the created data items as a string. If "__file__" is specified, the name will be that of each data file. The default is "__file__".
--data_source [source] The source of the data as a string. The default is "data_import". Set this if you wish to track where data comes from.
--data_tags [tag string] A space-separated list of tags to associated with the data items. The default is empty (no data item tags). Note that session tags, dataset tags, and data item tags are distinct and separate. It's a common mistake to specify -session_tags or -dataset_tags when -data_tags is intended. See Tags. discussion below.
--disable_encoding_check Item file uploads for files of type 'csv, txt and html' have to be strictly UTF-8 encoded. On upload, there is a check for UTF-8 encoding which is used to force this requirement. This check is enabled by default and uploads will fail if this check fails. You can disable this check using -disable_encoding_check if you feel that your file is correctly encoded.
--ext_files [ext [ext …]] --ext_tables [ext [ext …]] --ext_html [ext [ext …]] --ext_movies [ext [ext …]] --ext_images [ext [ext …]] --ext_text [ext [ext …]] --ext_scenes [ext [ext …]] The -ext_* options are used to map file extensions to a data item type. Each -ext_* option corresponds to a different data item type and specifies the filename extensions that should be identified as such. For example, using -ext_html html htm specifies that *.html and *.htm files should be imported as HTML data items. By default, *.png and *.jpg map to Image items, *.mp4 maps to Animation items, *.csv maps to Table items, *.stl, *.ply, *.csf, and *.avz map to Scene items, and File items, String items, Tree items, and HTML items have no explicit mapping. If no arguments are given after a -ext_* option, that specifies that no file extensions should be mapped to that data item type.
--table_col_labels --table_row_labels These two options specify that imported tables should consider the first column and first row, respectively, as labels for the table. If either of these options are omitted, it indicates that the column (or row) has no labels in the data file.
--table_numeric Using this option indicates that table data should be coerced into numeric data types instead of strings (the default).
--table_delimiter [char] The character that separates cell items from each other in an table input file. By default, the separator is a comma. Specifying nothing for -table_delimiter indicates that no separation should be done and each line is imported as a single cell item.
--table_quote_char [char] The character that delimits quoted text in cell items in a table input file. By default, the quote character is a single quote ('). This allows for the table delimiter to be used within a single cell. Specifying nothing for -table_quote_char indicates that no special parsing should occur for quoted strings.
--verbose Enables verbose output from the tool. When specified, this option will cause the tool to print many extra messages, including data types, files processed, etc.
--print_options Prints out the selected command line options.
--test Causes the tool to simulate the pushing of data items to an ADR server without actually doing so. This is helpful when debugging data import, especially when used in conjunction with the -verbose option.
List Sub-command (ls)#
usage: adr.bat ls [-h] [--full] [--long] [--guid] [--header] [--no-header]
[--type {item,session,dataset,template,category,group}] [--query query_string]
adr_server_url
List items, sessions, datasets and templates in the ADR server.
positional arguments:
adr_server_url ADR server URL. Example: http://nexus:cei@127.0.0.1:8000
options:
-h, --help show this help message and exit
--full Increase the level of output detail
--long One item per line
--guid Include the GUID in the output
--header Include headers in the output
--no-header Do not include headers in the output
--type {item,session,dataset,template,category,group}
Select the object type to list. Default: item
--query query_string Specify a query string. Default: no filter
Description#
This tool selects a collection of objects and prints the details of the objects to stdout.
Arguments#
adr_server_url This argument specifies the hostname, port, username and password of the ADR server to list items from. For example: http://nexus:cei@127.0.0.1:8000 specifies a server running on the local machine (127.0.0.1) on port 8000. The username is 'nexus' and the password is 'cei'.
Options#
Various options exist.
-h, --help Show the usage message and exit
--verbose Display additional status and progress information during the operation.
--full Display additional information not included in a simple listing. This option implies --long
--long Display a single item on a each line.
--header, --no-header Display If --header is specified, then some query details will be printed at the start of the operation. --no-header suppresses the query details (the default).
--guid Display include the GUID for each object in addition to other selected information.
--verbose Display additional status and progress information during the operation.
--type {item,template,dataset,template,category,group} Specify the type of objects to list.
--query query_string Use the specified query string to select the specific objects of the specified type (--type option) to perform the operation on. The syntax is documented here.
Delete Sub-command (rm)#
usage: adr.bat rm [-h] [--type {item,template}] [--query query_string] [--verbose] [--test] adr_server_url
Delete selected items or report templates from the ADR server. Note: if the query type is 'template', the query will be
automatically prefixed to restrict the query to top level templates. Only top level templates may be deleted and if they
are, all of their children will be deleted as well.
positional arguments:
adr_server_url ADR server URL. Example: http://nexus:cei@127.0.0.1:8000
options:
-h, --help show this help message and exit
--type {item,template}
Select the object type to remove. Default: item
--query query_string Specify a query string. Default: no filter
--verbose Enable verbose mode
--test Validate the operation, but do not perform it
Description#
This tool deletes a selected collection of objects (data items or templates) from a server.
Arguments#
adr_server_url This argument specifies the hostname, port, username and password of the ADR server to delete items from. For example: http://nexus:cei@127.0.0.1:8000 specifies a server running on the local machine (127.0.0.1) on port 8000. The username is 'nexus' and the password is 'cei'.
Options#
Various options exist.
-h, --help Show the usage message and exit
--verbose Display additional status and progress information during the operation.
--test Causes the tool to simulate the operation without actually performing it. This is helpful when debugging command lines, especially when used in conjunction with the -verbose option.
--type {item,template} Specify the type of objects to delete. This command can delete data items or templates. It may delete sessions/datasets implicitly if they no are no longer referenced.
--query query_string Use the specified query string to select the specific objects of the specified type (--type option) to perform the operation on. The syntax is documented here.
HTML export command (htmlexport)#
usage: adr.bat htmlexport [-h] [--query query_string] [--filename top_level_filename] [--no_inline_files] [--verbose]
adr_server_url destination_directory
Export a selected report as offline html from the ADR server. Note: the template query will always include a top level
check. The report will be exported into the named destination directory, which must not exist. The default top level
filename will be index.html stored in the destination directory. The top level filename can be specified on the command line
and should include both filename and extension.
positional arguments:
adr_server_url ADR server URL. Example: http://nexus:cei@127.0.0.1:8000
destination_directory
Directory to save HTML report into. Must not exist.
options:
-h, --help show this help message and exit
--query query_string Query string used to select the report template to export. Default: no filter
--filename top_level_filename
The filename of the top-level file. Default: index.html
--no_inline_files Disable the use of data URIs in the output
--verbose Enable verbose mode
Description#
This tool generates a report on the ADR server and downloads the resulting html into a local directory structure. Note: some item types will be converted into forms that do not require a running ADR server.
Arguments#
adr_server_url This argument specifies the hostname, port, username and password of the ADR server to modify items on. For example: http://nexus:cei@127.0.0.1:8000 specifies a server running on the local machine (127.0.0.1) on port 8000. The username is 'nexus' and the password is 'cei'.
destination_directory The downloaded html/css/image and other files will be downloaded into this directory. This directory cannot exist before the operation is performed.
Options#
Various options exist.
-h, --help Show the usage message and exit
--query query_string This query string is used to select the report to be exported. The result of the query must be a single top level report template.
--filename top_level_filename By default, the top level HTML file will be named 'index.html' in the destination directory. This option can be used to specify a different filename.
--no_inline_files By default, the export operation uses data URI strings embedded in the HTML to represent some files. If this option is specified, separate disk files will be used instead, but the local HTML cannot be displayed in a browser without a server or special browser flags.
--verbose Display additional status and progress information during the operation.
PDF export command (pdfexport)#
usage: adr.bat pdfexport [-h] [--query query_string] [--verbose] adr_server_url pdf_filename
Export a selected report in pdf format from the ADR server. Note: the template query will always include a top level
check. The report will be written into the named file, which must not exist.
positional arguments:
adr_server_url ADR server URL. Example: http://nexus:cei@127.0.0.1:8000
pdf_filename Filename to save the PDF file as. Must not exist.
options:
-h, --help show this help message and exit
--query query_string Query string used to select the report template to export. Default: no filter
--verbose Enable verbose mode
Description#
This tool generates a report on the ADR server and renders the selected report into a local PDF format file.
Arguments#
adr_server_url This argument specifies the hostname, port, username and password of the ADR server to modify items on. For example: http://nexus:cei@127.0.0.1:8000 specifies a server running on the local machine (127.0.0.1) on port 8000. The username is 'nexus' and the password is 'cei'.
pdf_filename The name to save the PDF file as. Note: This file cannot exist before the operation is performed.
Options#
Various options exist.
-h, --help Show the usage message and exit
--query query_string This query string is used to select the report to be exported. The result of the query must be a single top level report template.
--verbose Display additional status and progress information during the operation.
Tagging command (tag)#
usage: adr.bat tag [-h] [--value VALUE] [--type {item,session,dataset,template}] [--query query_string] [--verbose]
[--test]
adr_server_url {add,remove,replace} tagname
Modify item, template, session, and dataset object tags in the ADR server.
positional arguments:
adr_server_url ADR server URL. Example: http://nexus:cei@127.0.0.1:8000
{add,remove,replace} Tag operation
tagname The tag to modify
options:
-h, --help show this help message and exit
--value VALUE Tag value if needed
--type {item,session,dataset,template}
Select the object type to list. Default: item
--query query_string Specify a query string. Default: no filter
--verbose Enable verbose mode
--test Validate the operation, but do not perform it
Description#
This tool walks a collection of objects (data items, sessions, datasets or templates) selected via a query string and manipulates the tag strings. Consider a tag of the form tag_name=value, where '=value' is optional. tag_name is specified via an argument and value may be specified via the --value option. The resulting tag can be added to, removed from or modified on the selected objects. This tool will not add a tag multiple times to the same object.
Arguments#
adr_server_url This argument specifies the hostname, port, username and password of the ADR server to modify items on. For example: http://nexus:cei@127.0.0.1:8000 specifies a server running on the local machine (127.0.0.1) on port 8000. The username is 'nexus' and the password is 'cei'.
tag_operation {add,remove,replace} This argument selects the type of modification to apply to the named tag. Options include: add - add the tag to the items, remove - remove the tag from the items, replace - replace the tag. Replace will add the tag if is does not exist. If it does exist, the value of the tag will be changed or removed, depending on the --value option.
tag_name The actual tag name to modify.
Options#
Various options exist.
-h, --help Show the usage message and exit
--value [value] Specify the tag's value, forming the string: {tag_name}={value} to be used as the tag. If value is not specified, the tag will be simply {tag_name}.
--verbose Display additional status and progress information during the operation.
--test Causes the tool to simulate the operation without actually performing it. This is helpful when debugging command lines, especially when used in conjunction with the -verbose option.
--type {item,template,session,dataset} Specify the type of objects to modify the tags on. This command can work on data items, sessions, datasets or templates.
--query query_string Use the specified query string to select the specific objects of the specified type (--type option) to perform the operation on. The syntax is documented here.