Download this example as a Jupyter notebook or a Python script.

Getting started#

This example shows how to connect to Granta MI and perform basic operations on record lists.

Connect to Granta MI#

First, use the ansys.grantami.recordlists.Connection class to connect to the Granta MI server. The Connection class uses a fluent interface to build the connection, which is always invoked in the following sequence:

Specify your Granta MI Service Layer URL as a parameter to the Connection class.
Specify the authentication method using a Connection.with_...() method.
Use the Connection.connect() method to finalize the connection.

This returns a client object, called client in these examples.

[1]:

from ansys.grantami.recordlists import Connection, RecordListItem

connection = Connection("http://my_grantami_server/mi_servicelayer").with_autologon()
client = connection.connect()

Create a new record list#

API operations expect a RecordList instance as input. For the purpose of this example, create a new record list, using the create_list method. It returns a RecordList instance.

[2]:

example_list = client.create_list(
    name="Example list",
    description=f"Created by example 00_Basic_usage",
)
example_list

[2]:

<RecordList name: Example list>

Get the details of an existing record list#

The get_list method allows obtaining a RecordList instance from an existing record list unique identifier. This can be useful when the identifier is already known, for example if it has been obtained from the Favorites application or if it is hard-coded in the script configuration.

[3]:

list_details = client.get_list(example_list.identifier)
list_details

[3]:

<RecordList name: Example list>

[4]:

print(f"Name: {list_details.name}")
print(f"Identifier: {list_details.identifier}")
print(f"Notes: {list_details.notes}")
print(f"Description: {list_details.description}")
print(f"Created timestamp: {list_details.created_timestamp}")

Name: Example list
Identifier: 8bc61440-f110-4f63-b6ee-c72bb22ac7a9
Notes: None
Description: Created by example 00_Basic_usage
Created timestamp: 2024-12-13 15:47:13.900000+00:00

Get all record lists#

[5]:

all_lists = client.get_all_lists()
all_lists

[5]:

[<RecordList name: Example list>]

Copy a record list#

[6]:

list_copy = client.copy_list(example_list)
list_copy

[6]:

<RecordList name: Example list copy_20241213104714>

Update a record list#

[7]:

updated_list_copy = client.update_list(
    list_copy,
    name="Copied - Example List",
    description=None,
    notes="Copy of the example list",
)
print(f"Name: {updated_list_copy.name}")
print(f"Identifier: {updated_list_copy.identifier}")
print(f"Notes: {updated_list_copy.notes}")
print(f"Description: {updated_list_copy.description}")
print(f"Created timestamp: {updated_list_copy.created_timestamp}")

Name: Copied - Example List
Identifier: 32bbcf29-2375-433f-94a6-5f89ab2a9d0e
Notes: Copy of the example list
Description: None
Created timestamp: 2024-12-13 15:47:14.223000+00:00

Delete a record list#

[8]:

client.delete_list(updated_list_copy)

Read the items in a record list#

The list was created at the beginning of this example, so the list is currently empty.

[9]:

items = client.get_list_items(example_list)
items

[9]:

[]

Add items to a record list#

Add items to a list using add_items_to_list. Items are described using the database GUID, table GUID, and record history GUID.

[10]:

client.add_items_to_list(
    example_list,
    items=[
        RecordListItem(
            database_guid="e595fe23-b450-4d18-8c08-4a0f378ef095",
            table_guid="81dff531-0254-4fbe-9621-174b10aaee3d",
            record_history_guid="3bc2b82f-0199-4f3b-a7af-8d520250b180",
        ),
    ],
)

[10]:

[<RecordListItem(database_guid='e595fe23-b450-4d18-8c08-4a0f378ef095', record_history_guid='3bc2b82f-0199-4f3b-a7af-8d520250b180')>]

Then retrieve the items and confirm that the record list now includes the added items.

[11]:

list_items = client.get_list_items(example_list)
list_items

[11]:

[<RecordListItem(database_guid='e595fe23-b450-4d18-8c08-4a0f378ef095', record_history_guid='3bc2b82f-0199-4f3b-a7af-8d520250b180')>]

Remove items from a record list#

Remove items from a record list using remove_items_from_list.

[12]:

client.remove_items_from_list(
    example_list,
    items=list_items,
)

[12]:

[]

Then retrieve the items again and confirm that the record list is empty.

[13]:

items = client.get_list_items(example_list)
items

[13]:

[]