{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "52e1b6ef",
   "metadata": {},
   "source": [
    "# Publishing, revising, and withdrawing record lists\n",
    "This example shows how to connect to Granta MI and perform advanced operations on record lists,\n",
    "such as publishing, withdrawing, and revising a list. For more information about the concepts\n",
    "discussed here, see the Help in the Granta MI Favorites app."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "5fea6cab",
   "metadata": {},
   "source": [
    ".. note:: Running this notebook requires permissions to request publication of, to publish, and to\n",
    "revise a record list. Contact your Granta MI administrator for more information."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "927d8ae6",
   "metadata": {},
   "source": [
    "## Connect to Granta MI and create a record list"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "c0c0cff8",
   "metadata": {},
   "source": [
    "Import the ``Connection`` class and create the connection. See the\n",
    "[Getting started](00_basic_usage.ipynb) example for more details."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "081651a5",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "from ansys.grantami.recordlists import Connection\n",
    "\n",
    "connection = Connection(\"http://my_grantami_server/mi_servicelayer\").with_autologon()\n",
    "client = connection.connect()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "120b2c80",
   "metadata": {},
   "source": [
    "Create a record list for use in this example."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "b8211f36",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "example_list = client.create_list(\n",
    "    name=\"Example list\",\n",
    "    description=f\"Created by example 01_Advanced_usage\",\n",
    ")\n",
    "example_list"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "f048593f",
   "metadata": {
    "lines_to_next_cell": 2
   },
   "source": [
    "Record lists include two properties describing two aspects of their status: whether they are\n",
    "awaiting approval to be published, and whether they are currently published.\n",
    "Define a function to display the status properties."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "ec7cc3bc",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "def print_status(record_list):\n",
    "    print(f\"Awaiting approval: {record_list.awaiting_approval}\")\n",
    "    print(f\"Published: {record_list.published}\")\n",
    "\n",
    "\n",
    "print_status(example_list)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "811f1f22",
   "metadata": {},
   "source": [
    "## Publish a record list"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "2bd4657d",
   "metadata": {},
   "source": [
    "A record list is proposed for publication by calling the ``request_list_approval`` method with the\n",
    "record list to be published."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "24ad6a6f",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "updated_list = client.request_list_approval(example_list)\n",
    "\n",
    "print_status(updated_list)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "29dc3c8e",
   "metadata": {},
   "source": [
    "Publish the record list by using the ``publish_list`` method."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "01131432",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "updated_list = client.publish_list(example_list)\n",
    "\n",
    "print_status(updated_list)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "970e1d6f",
   "metadata": {},
   "source": [
    "## Revise a record list"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "9fba725e",
   "metadata": {},
   "source": [
    "A published record list cannot be modified directly. Instead, first create a revision of the\n",
    "published record list using the ``revise_list`` method. This creates an editable copy of the\n",
    "original record list (a list revision), and leaves the original record list unchanged."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "a66c9038",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "revision_list = client.revise_list(example_list)\n",
    "\n",
    "print_status(revision_list)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "cbe09e4c",
   "metadata": {},
   "source": [
    "The record list revision includes a property tracking the parent record list:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "c760a7ce",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "print(f\"Is revision: {revision_list.is_revision}\")\n",
    "print(f\"Parent identifier: {revision_list.parent_record_list_identifier}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "4ecb5799",
   "metadata": {},
   "source": [
    "Modifications made to the list revision are applied to the original list when the list revision\n",
    "is published. Once the original list is updated, the list revision is deleted and is no longer\n",
    "available."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "8f73e7b5",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "updated_revision_list = client.update_list(revision_list, notes=\"Added during revision process\")\n",
    "updated_revision_list = client.request_list_approval(updated_revision_list)\n",
    "updated_original_list = client.publish_list(updated_revision_list)\n",
    "\n",
    "# When publishing a revision list, the returned object is the updated parent list.\n",
    "# Check the notes of the list to confirm the revisions were made successfully.\n",
    "print(f\"Notes: {updated_original_list.notes}\")\n",
    "print(f\"Is published: {updated_original_list.published}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "8f9a7680",
   "metadata": {},
   "source": [
    "## Withdraw a record list\n",
    "When a record list is in the published state, calling ``request_list_approval`` requests the\n",
    "withdrawal of that list."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "c9ede27d",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "updated_list = client.request_list_approval(example_list)\n",
    "\n",
    "print_status(updated_list)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "a4591b84",
   "metadata": {},
   "source": [
    "Use the ``unpublish_list`` method to withdraw a record list."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "fb149f29",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "updated_list = client.unpublish_list(example_list)\n",
    "\n",
    "print_status(updated_list)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "d22c1995",
   "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
}