{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "79510fa7",
   "metadata": {},
   "source": [
    "# Getting started\n",
    "This example shows how to connect to Granta MI and perform basic operations on record lists."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "2c25ccfe",
   "metadata": {},
   "source": [
    "## Connect to Granta MI"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "92c90cdc",
   "metadata": {},
   "source": [
    "First, use the ``ansys.grantami.recordlists.Connection`` class to connect to the Granta MI\n",
    "server. The ``Connection`` class uses a fluent interface to build the connection, which is\n",
    "always invoked in the following sequence:\n",
    "\n",
    "1. Specify your Granta MI Service Layer URL as a parameter to the ``Connection`` class.\n",
    "2. Specify the authentication method using a ``Connection.with_...()`` method.\n",
    "3. Use the ``Connection.connect()`` method to finalize the connection.\n",
    "\n",
    "This returns a client object, called ``client`` in these examples."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "f8d70d64",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "from ansys.grantami.recordlists import Connection, RecordListItem\n",
    "\n",
    "connection = Connection(\"http://my_grantami_server/mi_servicelayer\").with_autologon()\n",
    "client = connection.connect()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "456b3e67",
   "metadata": {},
   "source": [
    "## Create a new record list\n",
    "API operations expect a ``RecordList`` instance as input. For the purpose of this example, create\n",
    "a new record list, using the ``create_list`` method. It returns a ``RecordList`` instance."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "e5995007",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "example_list = client.create_list(\n",
    "    name=\"Example list\",\n",
    "    description=f\"Created by example 00_Basic_usage\",\n",
    ")\n",
    "example_list"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "8fca331e",
   "metadata": {},
   "source": [
    "## Get the details of an existing record list\n",
    "The ``get_list`` method allows obtaining a ``RecordList`` instance from an existing record list\n",
    "unique identifier. This can be useful when the identifier is already known, for example if it has\n",
    "been obtained from the Favorites application or if it is hard-coded in the script configuration."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "63bfc041",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "list_details = client.get_list(example_list.identifier)\n",
    "list_details"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "65abd56b",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "print(f\"Name: {list_details.name}\")\n",
    "print(f\"Identifier: {list_details.identifier}\")\n",
    "print(f\"Notes: {list_details.notes}\")\n",
    "print(f\"Description: {list_details.description}\")\n",
    "print(f\"Created timestamp: {list_details.created_timestamp}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "7eeeebb7",
   "metadata": {},
   "source": [
    "## Get all record lists"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "58ff0d49",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "all_lists = client.get_all_lists()\n",
    "all_lists"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "963ed3b7",
   "metadata": {},
   "source": [
    "## Copy a record list"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "c9acc812",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "list_copy = client.copy_list(example_list)\n",
    "list_copy"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "0235c4b1",
   "metadata": {},
   "source": [
    "## Update a record list"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "123fa919",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "updated_list_copy = client.update_list(\n",
    "    list_copy,\n",
    "    name=\"Copied - Example List\",\n",
    "    description=None,\n",
    "    notes=\"Copy of the example list\",\n",
    ")\n",
    "print(f\"Name: {updated_list_copy.name}\")\n",
    "print(f\"Identifier: {updated_list_copy.identifier}\")\n",
    "print(f\"Notes: {updated_list_copy.notes}\")\n",
    "print(f\"Description: {updated_list_copy.description}\")\n",
    "print(f\"Created timestamp: {updated_list_copy.created_timestamp}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "8c993b12",
   "metadata": {},
   "source": [
    "## Delete a record list"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "29d1784c",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "client.delete_list(updated_list_copy)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "7d3d4098",
   "metadata": {},
   "source": [
    "## Read the items in a record list\n",
    "The list was created at the beginning of this example, so the list is currently empty."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "182fc6bc",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "items = client.get_list_items(example_list)\n",
    "items"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "5824a21d",
   "metadata": {},
   "source": [
    "## Add items to a record list\n",
    "Add items to a list using ``add_items_to_list``.\n",
    "Items are described using the database GUID, table GUID, and record history GUID."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "de6b8304",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "client.add_items_to_list(\n",
    "    example_list,\n",
    "    items=[\n",
    "        RecordListItem(\n",
    "            database_guid=\"e595fe23-b450-4d18-8c08-4a0f378ef095\",\n",
    "            table_guid=\"81dff531-0254-4fbe-9621-174b10aaee3d\",\n",
    "            record_history_guid=\"3bc2b82f-0199-4f3b-a7af-8d520250b180\",\n",
    "        ),\n",
    "    ],\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "9ba4f8f1",
   "metadata": {},
   "source": [
    "Then retrieve the items and confirm that the record list now includes the added items."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "3790b3a7",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "list_items = client.get_list_items(example_list)\n",
    "list_items"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "b118d1f7",
   "metadata": {},
   "source": [
    "## Remove items from a record list\n",
    "Remove items from a record list using ``remove_items_from_list``."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "4aa5c516",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "client.remove_items_from_list(\n",
    "    example_list,\n",
    "    items=list_items,\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "c5c4a89d",
   "metadata": {},
   "source": [
    "Then retrieve the items again and confirm that the record list is empty."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "f132dccd",
   "metadata": {
    "lines_to_next_cell": 2,
    "tags": []
   },
   "outputs": [],
   "source": [
    "items = client.get_list_items(example_list)\n",
    "items"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "65da8e21",
   "metadata": {
    "nbsphinx": "hidden"
   },
   "outputs": [],
   "source": [
    "client.delete_list(example_list)"
   ]
  }
 ],
 "metadata": {
  "jupytext": {
   "formats": "ipynb,py:light"
  },
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "language": "python",
   "name": "python3"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}