Common

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.

The database_key argument is required if Granta MI is configured to use a value other than MI_Restricted_Substances for the Restricted Substances and Sustainability database.

A table_name argument is required for each table in the Restricted Substances and Sustainability database that has been renamed.

If external records are used in any analysis, the database key for those records should not be provided here. Instead, it should be provided in the appropriate query build method or in the XML BoM. See Using external records in analysis for more details.

Parameters:

database_keystr, optional

Database key for the Restricted Substances and Sustainability 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 Locations schema. The default is None, in which case Locations 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

  • Locations

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

Value with unit

class ValueWithUnit(value, unit)

Describes a value obtained from the API.

Added in version 2.0.

property unit: str

Unit of the value.

property value: float

Real number.

Record references

See Record identification for more information about populated properties on record reference objects.

class PartReference(input_part_number=None, equivalent_references=None, **kwargs)

Represents a reference to a part record.

This class extends the base class to also support part numbers.

property record_history_identity: int | None

Record history identity.

property record_history_guid: str | None

Record history GUID.

property record_guid: str | None

Record GUID.

property database_key: str | None

The database key for the database that contains the record.

This property is only populated if the record is in a different database to the one specified in BomAnalyticsClient.set_database_details(). Supported by MI Restricted Substances and Sustainability Reports 2026 R1 or later.

Added in version 2.4.

property identity: str | None

Item unique identifier.

This property is only populated on BoM query results and is equal to the id attribute of the corresponding input BoM item. If no id has been defined on the BoM item, a unique auto-generated value is assigned during analysis.

property external_identity: str | None

Item external identity.

This property is only populated on BoM query results and is equal to the <ExternalIdentity> element of the corresponding input BoM item.

property name: str | None

Item name.

This property is only populated on BoM query results and is equal to the <Name> element of the corresponding input BoM item.

property part_number: str | None

Part number.

property input_part_number: str | None

Input part number.

This property is only populated on BoM query results and is equal to the <PartNumber> element of the corresponding input BoM item.

property equivalent_references: list[PartReference] | None

Other part records which are defined as being equivalent to this record.

Only populated if this record is a substitute for a record in a different database during analysis via a cross-database link.

Added in version 2.4.

class SpecificationReference(equivalent_references=None, **kwargs)

Represents a reference to a specification record.

This class extends the base class to also support specification IDs.

property record_history_identity: int | None

Record history identity.

property record_history_guid: str | None

Record history GUID.

property record_guid: str | None

Record GUID.

property database_key: str | None

The database key for the database that contains the record.

This property is only populated if the record is in a different database to the one specified in BomAnalyticsClient.set_database_details(). Supported by MI Restricted Substances and Sustainability Reports 2026 R1 or later.

Added in version 2.4.

property identity: str | None

Item unique identifier.

This property is only populated on BoM query results and is equal to the id attribute of the corresponding input BoM item. If no id has been defined on the BoM item, a unique auto-generated value is assigned during analysis.

property external_identity: str | None

Item external identity.

This property is only populated on BoM query results and is equal to the <ExternalIdentity> element of the corresponding input BoM item.

property name: str | None

Item name.

This property is only populated on BoM query results and is equal to the <Name> element of the corresponding input BoM item.

property specification_id: str | None

Specification ID.

property equivalent_references: list[SpecificationReference] | None

Other specification records which are defined as being equivalent to this record.

Only populated if this record is a substitute for a record in a different database during analysis via a cross-database link.

Added in version 2.4.

class MaterialReference(equivalent_references=None, **kwargs)

Represents a reference to a material record.

This class extends the base class to also support material IDs.

property record_history_identity: int | None

Record history identity.

property record_history_guid: str | None

Record history GUID.

property record_guid: str | None

Record GUID.

property database_key: str | None

The database key for the database that contains the record.

This property is only populated if the record is in a different database to the one specified in BomAnalyticsClient.set_database_details(). Supported by MI Restricted Substances and Sustainability Reports 2026 R1 or later.

Added in version 2.4.

property identity: str | None

Item unique identifier.

This property is only populated on BoM query results and is equal to the id attribute of the corresponding input BoM item. If no id has been defined on the BoM item, a unique auto-generated value is assigned during analysis.

property external_identity: str | None

Item external identity.

This property is only populated on BoM query results and is equal to the <ExternalIdentity> element of the corresponding input BoM item.

property name: str | None

Item name.

This property is only populated on BoM query results and is equal to the <Name> element of the corresponding input BoM item.

property material_id: str | None

Material ID.

property equivalent_references: list[MaterialReference] | None

Other material records which are defined as being equivalent to this record.

Only populated if this record is a substitute for a record in a different database during analysis via a cross-database link.

Added in version 2.4.

class CoatingReference(equivalent_references=None, **kwargs)

Represents a reference to a coating record.

property record_history_identity: int | None

Record history identity.

property record_history_guid: str | None

Record history GUID.

property record_guid: str | None

Record GUID.

property database_key: str | None

The database key for the database that contains the record.

This property is only populated if the record is in a different database to the one specified in BomAnalyticsClient.set_database_details(). Supported by MI Restricted Substances and Sustainability Reports 2026 R1 or later.

Added in version 2.4.

property identity: str | None

Item unique identifier.

This property is only populated on BoM query results and is equal to the id attribute of the corresponding input BoM item. If no id has been defined on the BoM item, a unique auto-generated value is assigned during analysis.

property equivalent_references: list[CoatingReference] | None

Other coating records which are defined as being equivalent to this record.

Only populated if this record is a substitute for a record in a different database during analysis via a cross-database link.

Added in version 2.4.

class ProcessReference(equivalent_references=None, **kwargs)

Represents a reference to a process record.

Added in version 2.0.

property record_history_identity: int | None

Record history identity.

property record_history_guid: str | None

Record history GUID.

property record_guid: str | None

Record GUID.

property database_key: str | None

The database key for the database that contains the record.

This property is only populated if the record is in a different database to the one specified in BomAnalyticsClient.set_database_details(). Supported by MI Restricted Substances and Sustainability Reports 2026 R1 or later.

Added in version 2.4.

property identity: str | None

Item unique identifier.

This property is only populated on BoM query results and is equal to the id attribute of the corresponding input BoM item. If no id has been defined on the BoM item, a unique auto-generated value is assigned during analysis.

property external_identity: str | None

Item external identity.

This property is only populated on BoM query results and is equal to the <ExternalIdentity> element of the corresponding input BoM item.

property name: str | None

Item name.

This property is only populated on BoM query results and is equal to the <Name> element of the corresponding input BoM item.

property equivalent_references: list[ProcessReference] | None

Other process records which defined as being equivalent to this record.

Only populated if this record is a substitute for a record in a different database during analysis via a cross-database link.

Added in version 2.4.

class SubstanceReference(equivalent_references=None, **kwargs)

Represents a reference to a substance record.

This class extends the base constructor to also support CAS numbers, EC numbers, and chemical names.

Substance references come in multiple flavors. Inputs, compliance results, and impacted substance results quantify substances in slightly different ways. This class implements the reference aspects of the substance record only. The quantifications are implemented in the subclasses.

property record_history_identity: int | None

Record history identity.

property record_history_guid: str | None

Record history GUID.

property record_guid: str | None

Record GUID.

property database_key: str | None

The database key for the database that contains the record.

This property is only populated if the record is in a different database to the one specified in BomAnalyticsClient.set_database_details(). Supported by MI Restricted Substances and Sustainability Reports 2026 R1 or later.

Added in version 2.4.

property identity: str | None

Item unique identifier.

This property is only populated on BoM query results and is equal to the id attribute of the corresponding input BoM item. If no id has been defined on the BoM item, a unique auto-generated value is assigned during analysis.

property external_identity: str | None

Item external identity.

This property is only populated on BoM query results and is equal to the <ExternalIdentity> element of the corresponding input BoM item.

property name: str | None

Item name.

This property is only populated on BoM query results and is equal to the <Name> element of the corresponding input BoM item.

property cas_number: str | None

CAS number.

property ec_number: str | None

EC number.

property chemical_name: str | None

Chemical name.

property equivalent_references: list[SubstanceReference] | None

Other substance records which are defined as being equivalent to this record.

Only populated if this record is a substitute for a record in a different database during analysis via a cross-database link.

Added in version 2.4.

class TransportReference(equivalent_references=None, **kwargs)

Represents a reference to a transport record.

Added in version 2.0.

property record_history_identity: int | None

Record history identity.

property record_history_guid: str | None

Record history GUID.

property record_guid: str | None

Record GUID.

property database_key: str | None

The database key for the database that contains the record.

This property is only populated if the record is in a different database to the one specified in BomAnalyticsClient.set_database_details(). Supported by MI Restricted Substances and Sustainability Reports 2026 R1 or later.

Added in version 2.4.

property identity: str | None

Item unique identifier.

This property is only populated on BoM query results and is equal to the id attribute of the corresponding input BoM item. If no id has been defined on the BoM item, a unique auto-generated value is assigned during analysis.

property equivalent_references: list[TransportReference] | None

Other transport records which are defined as being equivalent to this record.

Only populated if this record is a substitute for a record in a different database during analysis via a cross-database link.

Added in version 2.4.