Server Object#

report_remote_server.Server object#

This object serves to wrap the Ansys Dynamic Reporting REST API. It sets up a connection to an ADR Nexus server and allows objects to be pulled from and pushed to the server.

A new server object can be created with the following:

serverobj = report_remote_server.Server(url=None, username=None, password=None)

Methods#

serverobj.set_URL(“http://localhost:8000”) serverobj.set_username(“nexus”) serverobj.set_password(“cei”)

Specify the ADR Nexus server (url and authentication information) to which to connect the Server object to.

url = serverobj.get_URL() username = serverobj.get_username() password = serverobj.get_password()

Retrieve information about the current Server configuration.

server_name = serverobj.get_server_name()

Attempts to connect to the database returns the name of the server. For remote servers, the name is a configuration parameter. For local servers, it is the name of the directory that contains the SQLite file. Note: if a connection to the server cannot be made or the server does not support names, this method returns the URL for the server.

server_version_float = serverobj.validate()

Attempts to connect to the database and verifies that the server connection specifications are valid. It returns the version of the ADR Nexus server API that the server is using. Note: this method will throw an exception on encountering an error.

has_database_url = serverobj.valid_database()

This method checks to see if a database url has been set. It returns True if a url has been set. It does not verify that the connection and username, password is valid.

serverobj.stop_local_server()

This method will stop any local ADR Nexus server accessible via the current Server object URL, username and password.

guid_list = serverobj.get_object_guids(objtype=type_class, query=None)

This method will query the server and returns a list of the object GUIDs that meet the specific query. If the query is None, all of the GUIDs of the type specified by objtype will be returned. The objtype keyword specifies the type of database object to get the list of guids for. Valid values for the objtype keyword include:

  • report_objects.DatasetREST

  • report_objects.SessionREST

  • report_objects.ItemREST

obj_list = serverobj.get_objects(objtype=type_class, query=None)

This method is similar to get_object_guids() except that it returns a list of actual instances of the class specified by the objtype keyword instead of just returning the GUIDs.

Note that if you want the list of templates, you can either set objtype to report_objects.TempalteREST or to report.objects.TemplateREST.factory. In the first case, all the templates will be returned as objects of the TemplateREST class. In the second case, all templates will be returned as objects of the sub-classes of TemplateREST, corresponding to the exact report_type.

obj = serverobj.get_object_from_guid(guid, objtype=type_class)

This method queries the ADR Nexus server for a single object of the class specified by objtype with the GUID specified by the guid argument. It returns an instance of the class specified by objtype or None if the GUID is not present.

status_code = serverobj.put_objects(objects)

This method takes a collection of objects of the classes report_objects.DatasetREST, report_objects.SessionREST and report_objects.ItemREST and pushes the local contents of the objects to the server. If objects with the same GUID(s) already exist in the server database, they will be overwritten. The return value is a status code from the requests Python module (e.g. requests.codes.ok). Note: if an error occurs the method will return the last error, but it will try to push every object in the input collection.

status_code = serverobj.del_objects(objects)

This method takes a collection of objects of the classes report_objects.DatasetREST, report_objects.SessionREST and report_objects.ItemREST and asks the server to delete them. If objects with matching GUIDs exist in the server database, they will be removed from the database. This method only looks at the guid attribute of the input object collection. The return value is a status code from the requests Python module (e.g. requests.codes.ok). Note: if an error occurs the method will return the last error, but it will try to delete every object in the input collection.

status_code = serverobj.get_file(object, fileobj)

In some cases, a report_objects.ItemREST instance will have an associated file in the Ansys Dynamic Reporting datastore. Examples include images, animations and 3D geometry (see report_objects.ItemRest above). The ItemREST.is_file_protocol() can be used to check for this. This method will download the file (if any) associated with the (ItemREST instance) object and write the output into the file object specified by the fileobj argument. Fileobj should be an open Python file type object that supports minimally write I/O semantics. Note that the operation is streaming, so it is possible for a partial file to exist if errors are encountered. The return value is a status code from the requests Python module (e.g. requests.codes.ok).

session = serverobj.get_default_session() dataset = serverobj.get_default_dataset() serverobj.set_default_session(session) serverobj.set_default_dataset(dataset)

The server object maintains default SessionREST and DatasetREST objects that are used with the create_item() method to simplify data item creation. The get_default_session() and get_default_dataset() methods return the current default session and dataset objects. The corresponding set_default_session() and set_default_dataset() methods set these objects to externally generated objects or more commonly, modified objects returned by the get methods.

item = serverobj.create_item(name=”Unnamed Item”, source=”ADR Python API”, sequence=0)

This method simplifies the generation of data items. One can create a new data item by simply instantiating an instance of ItemREST(), but many of the item attributes would need to be configured properly before the object can be saved into the database. Most notably, the item.session and item.dataset attributes need to be set to the GUIDs for an instance of SessionREST and DatasetREST respectively. The Server object always maintains a default instance of SessionREST and DatasetREST objects. The object references can be modified by the user to customize their metadata. The create_item() method will create a new instance of the ItemREST class and will automatically fill in the session and dataset attributes to the objects returned by get_default_session() and get_default_dataset(). Additionally, if put_objects() is called on an item whose session or dataset attributes match the default GUIDs, the put_objects() method will push the session and/or dataset objects as needed. If the session/dataset objects change (without changing the GUIDs) the system will detect this any automatically push them when the next item is pushed that references one of them. The create_item() method allows the user to specify the name, source and sequence number for the item during creation.

serverobj.export_report_as_html(report_guid, directory_name, query=None)

This method exports the Ansys Dynamic Reporting report with the GUID specified by the argument “report_guid”. The result will be written into the directory specified by the argument “directory_name”. The method will create the directory if it does not exist previously. There will be a file named “index.html” in the directory and a “media” subdirectory containing the resources needed to display the report. note: if there is an error, this method will throw an exception.

Input arguments:

  • report guid (string) - the guid of the report to be downloaded as HTML.

  • directory_name (string) - the name of the directory to save the downloaded contents.

  • query (dictionary) - a dictionary of query parameters to add to the report URL.

serverobj.export_report_as_pdf(report_guid, file_name, delay=5000)

Save a PDF rendering of the Ansys Dynamic Reporting report with the GUID specified by the argument “report_guid”. The name of the PDF file is specified by the argument “file_name”. Note: if there is an error, this method will throw an exception. This is the equivalent of displaying the report with the query ‘print=pdf’ included in the report URL.

Input arguments:

  • report guid (string) - the guid of the report to be saved as PDF.

  • file_name (string) - the name of the target PDF file.

  • delay (int) - number of milliseconds to wait for the report to load before downloading it. Default is 5000ms. Optional.

Various data items and report templates will behave differently when printing:

  1. Tree data items will be fully expanded and the interactive buttons for expanding/collapsing will be removed.

  2. Animation data items will be rendered as if the ‘image_display’ property is set to 1.

  3. Table data items will have all of their interactive controls suppressed (e.g. sorting, searching, scrolling, pagination, etc)

  4. Tab layouts will behave as if the ‘inline_tabs’ property is set to 1.

  5. Panel layouts will behave as if the ‘panel_template_toggle’ property is set to 0.

Magic tokens#

Magic tokens is a new way for users in the ADR Nexus server to login without using their password. Ansys Dynamic Reporting provides a Python API to generate a per-user secret token. This token can then be attached to any Ansys Dynamic Reporting web page URL to bypass login during future access. This is currently restricted to only the user who starts the server. This can be useful if a URL needs to be reused within a HTML iframe.

serverobj.generate_magic_token(max_age=None)

This method generates a magic token with the desired expiry.

Input arguments:

  • max_age (int) - Expiry of the token in seconds. If this is None, the server will use its default expiry of 1 day.

serverobj.get_url_with_magic_token()

This will return a URL to access the ADR Nexus server with a magic token attached.

Usage:

from ansys.dynamicreporting.core.utils import report_remote_server, report_objects

server = report_remote_server.Server()
opts = {
    "port": 8000,
    "directory": "C:\\Users\\Nexus\\db",
    "raise_exception": True,
    "connect": server,
}
launched = report_remote_server.launch_local_database_server(None, opts)
if launched:
    print(server.magic_token)  # auto generation.. default expiry of 1day
    print(server.get_url_with_magic_token())
    server.magic_token = server.generate_magic_token(
        max_age=60
    )  # manual generation, with an expiry of 60 seconds
    print(server.get_url_with_magic_token())
    # Prints URL with token.
    # Example: http://127.0.0.1:8000?magic_token=eyJ1c2VyX2lkIjozLCJtYXhfYWdlIjo4NjQwMCwidGltZXN0YW1wIjoiMW5QY1B5In0:1nPcPy:c3OZhMCVQQq_fXXzevQ47WHxYfbAZE5TI-GL0yBzIaw
    template = serverobj.create_template(
        name="New Template", parent=None, report_type="Layout:basic"
    )

Method on a report_remote_server.Server() object to create a new report_object.TemplateREST object. You can pass as input:

  • name (string) - the name of the template

  • parent (template objects)- the parent template. If None, the new template will be a top level one

  • report_type (string) - sets the type of template. Each value of report_type corresponds to a different template type, and will generate an object from the corresponding template sub-class. See the table for the accepted values of report_type, the corresponding template type and Python API sub-class.

error_string = serverobj.get_last_error()

Several of the server methods return REST error codes: put_objects(), del_objects(), get_file(), etc. When these methods error, they return the specific REST error code. If the error in question was generated by the ADR Nexus server, in addition to the error_code not being equal to requests.codes.ok, the server may return a more detailed error string. This string can be retrieved using the get_last_error() method. An example of a data item with an item name exceeding:

from ansys.dynamicreporting.core.utils import report_remote_server, report_objects

serverobj = report_remote_server.Server(
    url="http://localhost:8000", username="nexus", password="cei"
)
invalid_data_item_name = 100
item = serverobj.create_item(invalid_data_item_name, "command line")
item.set_payload_string("A simple text string")
print(serverobj.put_objects(item))
print(serverobj.get_last_error())

will output the following (note: requests.codes.bad_request == 400) output noting that the “name” field exceeds the maximum field length:

400 {“name”:[“Ensure this field has no more than 80 characters.”]}