Granta MI Connection

Connection Builder

class Connection(api_url, session_configuration=None)

Connects to an instance of Granta MI.

This is a subclass of ansys.openapi.common.ApiClientFactory. All methods within this class that are documented as returning ApiClientFactory return instances of ansys.grantami.bomanalytics.Connection instead.


Base URL of the API server.

session_configurationSessionConfiguration, optional

Additional configuration settings for the requests session. The default is None, in which case the class SessionConfiguration with default parameters is used.


For advanced usage, including configuring session-specific properties and timeouts, see ansys-openapi-common API Reference. Specifically, the documentation on the base class ApiClientFactory and the class SessionConfiguration.

To create the connection to Granta MI, you perform three steps:

  1. Create the connection builder object and specify the server to connect to.

  2. Specify the authentication method to use for the connection and provide credentials if required.

  3. Connect to the server, which returns the connection object.

The examples show this process for different authentication methods.


>>> cxn = Connection("http://my_mi_server/mi_servicelayer").with_autologon().connect()
>>> cxn
<BomServicesClient: url=http://my_mi_server/mi_servicelayer>
>>> cxn = (
...     Connection("http://my_mi_server/mi_servicelayer")
...     .with_credentials(username="my_username", password="my_password")
...     .connect()
... )
>>> cxn
<BomServicesClient: url=http://my_mi_server/mi_servicelayer>

Set up client authentication for use with Kerberos (also known as integrated Windows authentication).


Current client factory object.


Requires the user to have a valid Kerberos Ticket-Granting-Ticket (TGT).

  • On Windows, this is provided by default.

  • On Linux, this requires the [linux-kerberos] extension to be installed and your Kerberos installation to be configured correctly.

with_credentials(username, password, domain=None)

Set up client authentication for use with provided credentials.

This method will attempt to connect to the API and uses the provided WWW-Authenticate header to determine whether Negotiate, NTLM, or Basic Authentication should be used. The selected authentication method will then be configured for use.


Username for the connection.


Password for the connection.

domainstr, optional

Domain to use for connection if required. The default is None.


Original client factory object.


NTLM authentication is not currently supported on Linux.


Set up client authentication for use with OpenID Connect.

idp_session_configurationSessionConfiguration, optional

Additional configuration settings for the requests session when connected to the OpenID identity provider.


Builder object to authenticate via OIDC.


OIDC Authentication requires the [oidc] extra to be installed.


Set up client authentication for anonymous use. This does not configure any authentication or authorization headers. Users must provide any authentication information required themselves.

Clients relying on custom authentication such as client certificates or non-standard tokens should use this method.


Original client factory object.


Finalize the BoM Analytics client and return it for use.

Authentication must be configured for this method to succeed.


Client object that can be used to connect to Granta MI and perform BoM Analytics operations.


When the client is not fully configured.

BoM Analytics Client

class BomAnalyticsClient(servicelayer_url, **kwargs)

Communicates with Granta MI. This class is instantiated by the Connection class defined above and should not be instantiated directly.

run(query: MaterialImpactedSubstancesQuery) MaterialImpactedSubstancesQueryResult
run(query: MaterialComplianceQuery) MaterialComplianceQueryResult
run(query: PartImpactedSubstancesQuery) PartImpactedSubstancesQueryResult
run(query: PartComplianceQuery) PartComplianceQueryResult
run(query: SpecificationImpactedSubstancesQuery) SpecificationImpactedSubstancesQueryResult
run(query: SpecificationComplianceQuery) SpecificationComplianceQueryResult
run(query: SubstanceComplianceQuery) SubstanceComplianceQueryResult
run(query: BomImpactedSubstancesQuery) BomImpactedSubstancesQueryResult
run(query: BomComplianceQuery) BomComplianceQueryResult
run(query: Yaml) str
run(query: Type['Yaml']) str

Run a query against the Granta MI database.


A compliance, impacted substance, or yaml query object.

Query Result

The specific result object based on the provided query, which contains either the compliance or impacted substances results. In the case of a yaml query, a string is returned.


If the server encounters an error while processing the query with a severity of ‘critical’. This indicates that Granta MI is running and the BoM Analytics Service is available, but the query could not be run, probably because of a missing database or table.


If this exception is raised, the Granta MI server was not able to return a response, probably because of an internal configuration error or the BoM Analytics Service not being installed.

set_database_details(database_key='MI_Restricted_Substances', material_universe_table_name=None, in_house_materials_table_name=None, specifications_table_name=None, products_and_parts_table_name=None, substances_table_name=None, coatings_table_name=None)

Configure the database key and table names if different from the defaults.

A database key is required if Granta MI is configured to use a value other than MI_Restricted_Substances. A table name is required for each table in the Restricted Substances Database that has been renamed.

database_keystr, optional

Database key for the Restricted Substances database. The default is None, in which case MI_Restricted_Substances is used.

material_universe_table_namestr, optional

Name of the table that implements the MaterialUniverse schema. The default is None, in which case MaterialUniverse is used.

in_house_materials_table_namestr, optional

Name of the table that implements the Materials - in house schema. The default is None, in which case Materials - in house is used.

specifications_table_namestr, optional

Name of the table that implements the Specifications schema. The default is None, in which case Specifications is used.

products_and_parts_table_namestr, optional

Name of the table that implements the Products and parts schema. The default is None, in which case Products and parts is used.

substances_table_namestr, optional

Name of the table that implements the Restricted Substances schema. The default is None, in which case Restricted Substances is used.

coatings_table_namestr, optional

Name of the table that implements the Coatings schema. The default is None, in which case Coatings is used.


The database key and table names are configurable, but they only need to be specified if they have been modified from the defaults. Here is a summary of the default names:

  • Database key: MI_Restricted_Substances

  • Table names:

    • MaterialUniverse

    • Materials - in house

    • Specifications

    • Products and parts

    • Restricted Substances

    • Coatings


>>> cxn = Connection("http://localhost/mi_servicelayer").with_autologon().connect()
>>> cxn.set_database_details(database_key = "MY_RS_DB",
...                          in_house_materials_table_name = "My Materials")

Log Messages

class LogMessage(severity, message)

Message returned by Granta MI when running the query.

Messages marked with the error severity are more likely to produce incorrect results and should be treated with increased caution.


Either error, warning, or information.


Description of the issue.


class GrantaMIException

A critical error occurred when processing a BoM Analytics query.