docs/dsms_sdk/tutorials/3_updation.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# 3. Updating KItems with the SDK\n",
    "\n",
    "In this tutorial we see how to update existing Kitems."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 3.1. Setting up\n",
    "\n",
    "Before you run this tutorial: make sure to have access to a DSMS-instance of your interest, alongwith with installation of this package and have establised access to the DSMS through DSMS-SDK (refer to [Connecting to DSMS](../dsms_sdk.md#connecting-to-dsms))\n",
    "\n",
    "\n",
    "Now let us import the needed classes and functions for this tutorial."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [],
   "source": [
    "from dsms import DSMS, KItem"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now source the environmental variables from an `.env` file and start the DSMS-session."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [],
   "source": [
    "dsms = DSMS(env=\".env\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now lets get the kitem we created in the [2nd tutorial : Creation of Kitems](2_creation.ipynb)\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [],
   "source": [
    "item = dsms[\"ff1316ef-790c-4833-915c-de13c5f3ba91\"]"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "kitem:\n",
       "  name: Specimen123\n",
       "  id: ff1316ef-790c-4833-915c-de13c5f3ba91\n",
       "  ktype_id: specimen\n",
       "  slug: specimen123-ff1316ef\n",
       "  annotations: []\n",
       "  attachments:\n",
       "  - name: subgraph.ttl\n",
       "  linked_kitems: []\n",
       "  affiliations: []\n",
       "  authors:\n",
       "  - user_id: 7f0e5a37-353b-4bbc-b1f1-b6ad575f562d\n",
       "  avatar_exists: false\n",
       "  contacts: []\n",
       "  created_at: 2025-04-10 10:29:24.395884\n",
       "  updated_at: 2025-04-10 10:29:24.395884\n",
       "  external_links: []\n",
       "  apps: []\n",
       "  user_groups: []\n",
       "  custom_properties:\n",
       "    content:\n",
       "      sections:\n",
       "      - id: id0595fb5f1853a8\n",
       "        name: Untitled Section\n",
       "        entries:\n",
       "        - id: idba92210e193128\n",
       "          type: Number\n",
       "          label: Width\n",
       "          value: 0.5\n",
       "          measurementUnit:\n",
       "            iri: http://qudt.org/vocab/unit/MilliM\n",
       "            label: Millimetre\n",
       "            symbol: null\n",
       "            namespace: http://qudt.org/vocab/unit\n",
       "          relationMapping: null\n",
       "          required: false\n",
       "        - id: ida08bcc9977e388\n",
       "          type: Slider\n",
       "          label: Length\n",
       "          value:\n",
       "          - 0.1\n",
       "          - 0.2\n",
       "          measurementUnit:\n",
       "            iri: http://qudt.org/vocab/unit/MilliM\n",
       "            label: Millimetre\n",
       "            symbol: null\n",
       "            namespace: http://qudt.org/vocab/unit\n",
       "          relationMapping: null\n",
       "          required: false\n",
       "  rdf_exists: true"
      ]
     },
     "execution_count": 4,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "item"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 3.2. Updating Kitems"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now, we would like to update the properties of our KItem we created previously.\n",
    "\n",
    "Depending on the schema of each property (see [DSMS KItem Schema](../dsms_kitem_schema.md)), `list`accumulation (`+=` or `-=`), e.g. for the `annotations`, `attachments`, `external_link`, etc. \n",
    "\n",
    "**NOTE**: using `append` or `extend` will not validate the pydantic model of the respective fields and hence will cause an error during commiting. Hence, always use `+=`, `=` or `-=`.\n",
    "\n",
    "Other properties which are not `list`-like can be simply set by attribute-assignment (e.g. `name`, `slug`, `ktype_id`, etc)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [],
   "source": [
    "item.name = \"Specimen-123\"\n",
    "item.custom_properties.Width = 1\n",
    "item.attachments += [\"testfile.txt\"]\n",
    "item.annotations += [\"https://w3id.org/pmd/co/Specimen\"]\n",
    "item.external_links += [\n",
    "    {\"url\": \"http://specimens.org\", \"label\": \"specimen-link\"}\n",
    "]\n",
    "item.contacts += [{\"name\": \"Specimen preparation\", \"email\": \"specimenpreparation@group.mail\"}]"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [],
   "source": [
    "dsms.add(item)\n",
    "dsms.commit()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We can see now that the local system path of the attachment is changed to a simply file name, which means that the upload was successful. If not so, an error would have been thrown during the `commit`."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We can see the updates when we print the item:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "kitem:\n",
       "  name: Specimen-123\n",
       "  id: ff1316ef-790c-4833-915c-de13c5f3ba91\n",
       "  ktype_id: specimen\n",
       "  slug: specimen123-ff1316ef\n",
       "  annotations:\n",
       "  - iri: https://w3id.org/pmd/co/Specimen\n",
       "    label: Specimen\n",
       "    namespace: https://w3id.org/pmd/co\n",
       "  attachments:\n",
       "  - name: subgraph.ttl\n",
       "  - name: testfile.txt\n",
       "  linked_kitems: []\n",
       "  affiliations: []\n",
       "  authors:\n",
       "  - user_id: 7f0e5a37-353b-4bbc-b1f1-b6ad575f562d\n",
       "  avatar_exists: false\n",
       "  contacts:\n",
       "  - name: Specimen preparation\n",
       "    email: specimenpreparation@group.mail\n",
       "  created_at: 2025-04-10 10:29:24.395884\n",
       "  updated_at: 2025-04-10 10:30:00.537758\n",
       "  external_links:\n",
       "  - label: specimen-link\n",
       "    url: http://specimens.org\n",
       "  apps: []\n",
       "  user_groups: []\n",
       "  custom_properties:\n",
       "    content:\n",
       "      sections:\n",
       "      - id: id0595fb5f1853a8\n",
       "        name: Untitled Section\n",
       "        entries:\n",
       "        - id: idba92210e193128\n",
       "          type: Number\n",
       "          label: Width\n",
       "          value: 1\n",
       "          measurementUnit:\n",
       "            iri: http://qudt.org/vocab/unit/MilliM\n",
       "            label: Millimetre\n",
       "            symbol: null\n",
       "            namespace: http://qudt.org/vocab/unit\n",
       "          relationMapping: null\n",
       "          required: false\n",
       "        - id: ida08bcc9977e388\n",
       "          type: Slider\n",
       "          label: Length\n",
       "          value:\n",
       "          - 0.1\n",
       "          - 0.2\n",
       "          measurementUnit:\n",
       "            iri: http://qudt.org/vocab/unit/MilliM\n",
       "            label: Millimetre\n",
       "            symbol: null\n",
       "            namespace: http://qudt.org/vocab/unit\n",
       "          relationMapping: null\n",
       "          required: false\n",
       "  rdf_exists: true"
      ]
     },
     "execution_count": 7,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "item"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Furthermore we can also download the file we uploaded again:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "\t\t\t Downloaded file: subgraph.ttl\n",
      "|------------------------------------Beginning of file------------------------------------|\n",
      "@prefix ns1: <http://qudt.org/schema/qudt/> .\n",
      "@prefix ns2: <https://w3id.org/steel/ProcessOntology/> .\n",
      "@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .\n",
      "@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .\n",
      "\n",
      "<https://bue.materials-data.space/knowledge/specimen/specimen123-ff1316ef> a ns2:TestPiece ;\n",
      "    rdfs:label \"Specimen-123\"^^xsd:string ;\n",
      "    ns2:hasTotalLength_Object <https://bue.materials-data.space/knowledge/specimen/max_specimen123-ff1316ef>,\n",
      "        <https://bue.materials-data.space/knowledge/specimen/min_specimen123-ff1316ef> ;\n",
      "    ns2:hasWidth_Object <https://bue.materials-data.space/knowledge/specimen/emmo#EMMO_e4de48b1_dabb_4490_ac2b_040f926c64f0_specimen123-ff1316ef> .\n",
      "\n",
      "<https://bue.materials-data.space/knowledge/specimen/emmo#EMMO_e4de48b1_dabb_4490_ac2b_040f926c64f0_specimen123-ff1316ef> a <https://w3id.org/emmo#EMMO_e4de48b1_dabb_4490_ac2b_040f926c64f0> ;\n",
      "    ns1:hasUnit \"http://qudt.org/vocab/unit/MilliM\"^^xsd:anyURI ;\n",
      "    ns1:value 1 .\n",
      "\n",
      "<https://bue.materials-data.space/knowledge/specimen/max_specimen123-ff1316ef> a <https://w3id.org/emmo#EMMO_cd2cd0de_e0cc_4ef1_b27e_2e88db027bac> ;\n",
      "    ns1:hasUnit \"http://qudt.org/vocab/unit/MilliM\"^^xsd:anyURI ;\n",
      "    ns1:value \"0.2\"^^xsd:float .\n",
      "\n",
      "<https://bue.materials-data.space/knowledge/specimen/min_specimen123-ff1316ef> a <https://w3id.org/emmo#EMMO_cd2cd0de_e0cc_4ef1_b27e_2e88db027bac> ;\n",
      "    ns1:hasUnit \"http://qudt.org/vocab/unit/MilliM\"^^xsd:anyURI ;\n",
      "    ns1:value \"0.1\"^^xsd:float .\n",
      "\n",
      "\n",
      "|---------------------------------------End of file---------------------------------------|\n",
      "\n",
      "\n",
      "\t\t\t Downloaded file: testfile.txt\n",
      "|------------------------------------Beginning of file------------------------------------|\n",
      "This is a specimen preparation protocol!\n",
      "\n",
      "|---------------------------------------End of file---------------------------------------|\n",
      "\n",
      "\n"
     ]
    }
   ],
   "source": [
    "for file in item.attachments:\n",
    "    download = file.download()\n",
    "\n",
    "    print(\"\\t\\t\\t Downloaded file:\", file.name)\n",
    "    print(\"|------------------------------------Beginning of file------------------------------------|\")\n",
    "    print(download)\n",
    "    print(\"|---------------------------------------End of file---------------------------------------|\\n\\n\")"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.10.15"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}