Granta MI connection#

Connection builder#

class Connection(servicelayer_url, session_configuration=None)#

Connects to a Granta MI ServerAPI instance.

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.recordlists.Connection class instead.

Parameters:
servicelayer_urlstr

Base URL of the Granta MI Service Layer application.

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.

  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 client object.

The examples show this process for different authentication methods.

Examples

>>> client = Connection("http://my_mi_server/mi_servicelayer").with_autologon().connect()
>>> client
<RecordListsApiClient: url=http://my_mi_server/mi_servicelayer>
>>> client = (
...     Connection("http://my_mi_server/mi_servicelayer")
...     .with_credentials(username="my_username", password="my_password")
...     .connect()
... )
>>> client
<RecordListsApiClient: 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 RecordListsApiClient client and return it for use.

Authentication must be configured for this method to succeed.

Returns:
RecordListsApiClient

Client object that can be used to connect to Granta MI and interact with the record list API. The client object is a subtype of RecordListsApiClient. The subtype returned depends on the Granta MI server version.

RecordLists client#

class RecordListsApiClient(session, service_layer_url, configuration)#

Communicates with Granta MI.

This is an abstract class. Each concrete subtype of this class corresponds to a specific Granta MI server version.

Methods are only implemented if the underlying functionality is supported by the Granta MI server version. If the functionality is not available, a NotImplementedError is raised.

get_all_lists()#

Get the details of all record lists available for the current user.

This method is available for all supported versions of Granta MI.

Performs an HTTP request against the Granta MI Server API.

Returns:
list of RecordList

List of available record lists.

get_list(identifier)#

Get the details of a record list.

This method is available for all supported versions of Granta MI.

Performs an HTTP request against the Granta MI Server API.

Parameters:
identifierstr

Unique identifier of the record list.

Returns:
RecordList
search_for_lists(criterion, include_items=False)#

Search for record lists matching the provided criteria.

This method is available for all supported versions of Granta MI.

Performs multiple HTTP requests against the Server API.

Parameters:
criterionSearchCriterion | BooleanCriterion

Criterion to use to filter lists.

include_items: bool

Whether the search results should include record list items.

Returns:
list of SearchResult

List of record lists matching the provided criterion.

get_list_items(record_list)#

Get all items included in a record list.

This method is available for all supported versions of Granta MI.

Performs an HTTP request against the Granta MI Server API.

Parameters:
record_listRecordList

Record list for which items will be fetched.

Returns:
list of RecordListItem

List of items included in the record list.

get_resolvable_list_items(record_list, read_mode=False)#

Get all resolvable items included in a record list.

This method is available for all supported versions of Granta MI.

If an item cannot be resolved, it will not be returned. Performs multiple HTTP requests against the Granta MI Server API.

Added in version 1.2.

Parameters:
record_listRecordList

Record list for which items will be fetched.

read_modebool

Whether to enable read-mode for users who ordinarily have write permissions. Has no effect for read-only users.

Returns:
list of RecordListItem

List of items included in the record list.

Notes

Whether an item can be resolved depends on the role the user has on the Granta MI server. As a brief summary:

  • If the item doesn’t specify a version, this method tests if the user can access either the record or, if in a version-controlled table, a version of the record in any state. A record cannot be resolved if:

    • It has been deleted

    • It has been withdrawn and the user is a read user (version-controlled tables only)

    • It only has one unreleased version and the user is a read user (version-controlled tables only)

    • It is hidden by access control

  • If the item specifies a version, this method tests if the user can access that specific version of the record. This condition only applies to version-controlled tables. A record version cannot be resolved if:

    • It is unreleased and the user is a read user

    • It has been withdrawn and the user is a read user

    • It is hidden by access control

Since version control and access control is intended to allow and restrict access to records for certain groups of users, this method may return different results for different users depending on the configuration of Granta MI.

add_items_to_list(record_list, items)#

Add items to a record list.

This method is available for all supported versions of Granta MI.

Performs an HTTP request against the Granta MI Server API. Items are not validated against existing records on the server or existing items in the list.

Parameters:
record_listRecordList

Record list in which items will be added.

itemslist of RecordListItem

List of items to add to the record list.

Returns:
list of RecordListItem

List of items included in the record list.

remove_items_from_list(record_list, items)#

Remove items from a record list.

This method is available for all supported versions of Granta MI.

Performs an HTTP request against the Granta MI Server API. Attempting to remove items that are not in the list will not result in an error.

Parameters:
record_listRecordList

Record list from which items will be removed.

itemslist of RecordListItem

List of items to remove from the record list.

Returns:
list of RecordListItem

List of items included in the record list.

create_list(name, description=None, notes=None, items=None)#

Create a new record list with the provided arguments.

This method is available for all supported versions of Granta MI.

Performs an HTTP request against the Granta MI Server API.

Parameters:
namestr

Name of the record list.

descriptionstr or None

Description of the record list.

notesstr or None

Notes of the record list.

itemslist of RecordListItem or None

List of items to add to the record list.

Returns:
RecordList

Created record list details.

delete_list(record_list)#

Delete a record list.

This method is available for all supported versions of Granta MI.

Performs an HTTP request against the Granta MI Server API.

Parameters:
record_listRecordList

Record list to delete.

update_list(record_list, *, name='_ArgNotProvided', description='_ArgNotProvided', notes='_ArgNotProvided')#

Update a record list with the provided arguments.

This method is available for all supported versions of Granta MI.

Performs an HTTP request against the Granta MI Server API.

Parameters:
record_listRecordList

Record list to update.

namestr, optional

New value for the name of the record list.

descriptionstr or None, optional

New value for the description of the record list. Set to None to delete an existing value.

notesstr or None, optional

New value for the notes of the record list. Set to None to delete an existing value.

Returns:
RecordList

Updated representation of the record list.

copy_list(record_list)#

Create a copy of a record list.

This method is available for all supported versions of Granta MI.

Performs an HTTP request against the Granta MI Server API. The resulting list has a name prefixed by the original list name.

Parameters:
record_listRecordList

Record list to copy.

Returns:
RecordList

Record list created by the copy operation.

revise_list(record_list)#

Revise a record list.

This method is available for all supported versions of Granta MI.

Performs an HTTP request against the Granta MI Server API. Revising a list allows a user to create a personal copy of a published list and to modify its items or details. When the ‘in-revision’ list is published, it overwrites the original list.

Parameters:
record_listRecordList

Record list to revise.

Returns:
RecordList

Record list created by the revision operation.

request_list_approval(record_list)#

Request approval for a record list.

This method is available for all supported versions of Granta MI.

Performs an HTTP request against the Granta MI Server API. Requesting approval updates the awaiting approval status of the record list to True.

Parameters:
record_listRecordList

Record list for which approval is requested.

Returns:
RecordList

Updated representation of the record list.

publish_list(record_list)#

Publish a record list.

This method is available for all supported versions of Granta MI.

Performs an HTTP request against the Granta MI Server API. The list must be awaiting approval and not published already. Publishing the list updates the status to published and resets the awaiting approval status. Published lists can be viewed by all users and cannot be modified. To modify a published list, use revise_list().

Parameters:
record_listRecordList

Record list to publish.

Returns:
RecordList

Updated representation of the record list.

unpublish_list(record_list)#

Withdraw a record list.

This method is available for all supported versions of Granta MI.

Performs an HTTP request against the Granta MI Server API. The list must be published and awaiting approval. Withdrawing the list updates the published status to False and resets the awaiting approval status. All existing subscriptions will be lost on withdrawal.

Parameters:
record_listRecordList

Record list to unpublish.

Returns:
RecordList

Updated representation of the record list.

cancel_list_approval_request(record_list)#

Cancel a pending request for approval on a record list.

This method is available for all supported versions of Granta MI.

Performs an HTTP request against the Granta MI Server API. The list must be awaiting approval. Cancelling the approval request resets the awaiting approval status to False.

Parameters:
record_listRecordList

Record list for which to cancel the approval request.

Returns:
RecordList

Updated representation of the record list.

subscribe_to_list(record_list)#

Subscribe the current user to a record list.

This method is available for all supported versions of Granta MI.

Performs an HTTP request against the Granta MI Server API. The list must be published.

Parameters:
record_listRecordList

Record list to subscribe to.

Returns:
None
unsubscribe_from_list(record_list)#

Unsubscribe the current user from a record list.

This method is available for all supported versions of Granta MI.

Performs an HTTP request against the Granta MI Server API.

Parameters:
record_listRecordList

Record list to unsubscribe from.

Returns:
None
abstract get_all_audit_log_entries(page_size=100)#

Fetch all audit log entries for all lists that are visible to the current user.

This method is only supported when using Granta MI 2025 R2 or later.

Performs an HTTP request against the Granta MI Server API.

Added in version 2.0.

Parameters:
page_sizeint, optional (default: 100)

If None then all results will be fetched in one request, this may be a slow operation. If set to an int value then the results will be fetched in batches of size page_size.

Returns:
Iterator of AuditLogItem

Audit log entries.

Raises:
NotImplementedError

If this method is not supported by the Granta MI server.

abstract search_for_audit_log_entries(criterion, page_size=100)#

Fetch all audit log entries for all lists that are visible to the current user, filtered by a search criterion.

If the search criterion does not specify a list identifier, then all actions relating to deleted lists are excluded.

This method is only supported when using Granta MI 2025 R2 or later.

Performs an HTTP request against the Granta MI Server API.

Added in version 2.0.

Parameters:
criterionAuditLogSearchCriterion

Criterion by which to filter audit log entries.

page_sizeint, optional (default: 100)

If None then all results will be fetched in one request, this may be a slow operation. If set to an int value then the results will be fetched in batches of size page_size.

Returns:
Iterator of AuditLogItem

Audit log entries.

Raises:
NotImplementedError

If this method is not supported by the Granta MI server.