Granta MI connection

Connection builder

class Connection(api_url, session_configuration=None)

Connects to an instance of Granta MI.

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

Parameters:

api_urlstr

Base URL of the API server.

session_configurationSessionConfiguration, optional

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

Notes

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

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.

Examples

>>> 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>

with_autologon()

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

The default operation of this method is to attempt to connect to the API and to use the provided WWW-Authenticate header to determine if Negotiate authentication is supported by the server. If so, Negotiate will then be used for authentication.

If Negotiate authentication is not supported by the server, an exception is raised.

Returns:

ApiClientFactory

Current client factory object.

Raises:

ConnectionError

If the server does not support Negotiate authentication.

Notes

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, authentication_scheme=AuthenticationScheme.AUTO)

Set up client authentication for use with provided credentials.

The default operation of this method is to attempt to connect to the API and to use the provided WWW-Authenticate header to determine whether NTLM or Basic Authentication should be used. The selected authentication scheme will then be configured for use.

Parameters:

usernamestr

Username for the connection.

passwordstr

Password for the connection.

domainstr, optional

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

authentication_schemeAuthenticationScheme

The authentication scheme to use.

Tip

Added to ApiClientFactory.with_credentials in version 2.1 of ansys-openapi-common.

Returns:

ApiClientFactory

Original client factory object.

Raises:

ConnectionError

If the server does not support Basic or NTLM authentication (Windows clients only).

Notes

NTLM authentication is not currently supported on Linux.

with_oidc(idp_session_configuration=None)

Set up client authentication for use with OpenID Connect.

Parameters:

idp_session_configurationSessionConfiguration, optional

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

Returns:

OIDCSessionBuilder

Builder object to authenticate via OIDC.

Notes

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

with_anonymous()

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.

Returns:

ApiClientFactory

Original client factory object.

connect()

Finalize the BoM Analytics client and return it for use.

Authentication must be configured for this method to succeed.

Returns:

BomAnalyticsClient

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

Raises:

ValueError

When the client is not fully configured.

ConnectionError

If the resulting client cannot connect to the BoM Analytics service.

LicensingException

Error raised if no licenses were found.

BoM Analytics client

class BomAnalyticsClient(servicelayer_url, **kwargs)

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

property maximum_spec_link_depth: int | None

Maximum number of specification-to-specification links that are followed when processing a query. If a maximum is specified, specification-to-specification links are truncated at the specified depth, and only coatings and substances identified up to and including that point are included in the analysis.

The default is None, in which case no limit is applied to the number of specification-to-specification links. This might lead to performance issues if there are large numbers of specification-to-specification links present in the database.

This parameter is supported with Restricted Substances Reports 2023 R2 and later. With older reports, this parameter has no effect, all specification-to-specification links are followed.

Added in version 1.2.

Note

This limit applies to each branch of the BoM individually. This is not a global limit on the number of specification-to-specification links that are traversed across the entire BoM. Instead it is a limit on the maximum depth of specifications below any individual specification node.

Returns:

Optional[int]

Maximum depth of specification-to-specification links that are followed.

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: BomSustainabilityQuery) → BomSustainabilityQueryResult

run(query: BomSustainabilitySummaryQuery) → BomSustainabilitySummaryQueryResult

Run a query against the Granta MI database.

Parameters:

query

A compliance, impacted substances, or sustainability query object.

Returns:

Query Result

Specific result object based on the provided query, which contains either the compliance, impacted substances, or sustainability results.

Raises:

GrantaMIException

Error raised 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.

ApiException

Error raised if the Granta MI server is 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, process_universe_table_name=None, location_table_name=None, transport_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.

Parameters:

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.

process_universe_table_namestr, optional

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

location_table_namestr, optional

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

Added in version 2.0.

transport_table_namestr, optional

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

Added in version 2.0.

Notes

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

• Database key: MI_Restricted_Substances

• Table names:

  • MaterialUniverse

  • Materials - in house

  • Specifications

  • Products and parts

  • Restricted Substances

  • Coatings

  • ProcessUniverse

  • Location

  • Transport

Examples

>>> cxn = Connection("http://my_mi_server/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.

Attributes:

severitystr

Level of severity. Options are "error", "warning", and "information".

messagestr

Description of the issue.

Exceptions

class GrantaMIException

Provides the critical error message to show if processing a BoM Analytics query fails.

class LicensingException

Raised when an operation cannot be performed due to a lack of appropriate license.