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

Create the connection builder object and specify the server to connect to.
Specify the authentication method to use for the connection and provide credentials if required.
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).

Returns:

ApiClientFactory: Current client factory object.

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

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.

Parameters:

usernamestr: Username for the connection.
passwordstr: Password for the connection.
domainstr, optional: Domain to use for connection if required. The default is None.

Returns:

ApiClientFactory: Original client factory object.

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.

RecordLists client#

class RecordListsApiClient(session, service_layer_url, configuration)#

Communicates with Granta MI.

This class is instantiated by the Connection class and should not be instantiated directly.

get_all_lists()#

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

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

Performs an HTTP request against the Granta MI Server API.

Parameters:

record_listRecordList: Record list to unsubscribe from.

Returns:

None