APSToolkitPython/Tutorials/02. Explore Hubs - Projects - Items - URN.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<table align=\"left\">\n",
    "  <td style=\"text-align: center\">\n",
    "    <a href=\"https://colab.research.google.com/github/chuongmep/aps-toolkit/blob/dev/APSToolkitPython/Tutorials/02.%20Explore%20Hubs%20-%20Projects%20-%20Items%20-%20URN.ipynb\">\n",
    "      <img src=\"https://cloud.google.com/ml-engine/images/colab-logo-32px.png\" alt=\"Google Colaboratory logo\"><br> Run in Colab\n",
    "    </a>\n",
    "  </td>\n",
    "  <td style=\"text-align: center\">\n",
    "    <a href=\"https://github.com/chuongmep/aps-toolkit/blob/dev/APSToolkitPython/Tutorials/02.%20Explore%20Hubs%20-%20Projects%20-%20Items%20-%20URN.ipynb\">\n",
    "      <img src=\"https://cloud.google.com/ml-engine/images/github-logo-32px.png\" alt=\"GitHub logo\"><br> View on GitHub\n",
    "    </a>\n",
    "  </td>\n",
    "</table>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<table align=\"left\">\n",
    "  <tr>\n",
    "    <td>Author(s)</td>\n",
    "    <td><a href=\"https://github.com/chuongmep\" id=\"author-link\">Chuong Ho</a></td>\n",
    "    <!-- <td><a href=\"<your repo>\" id=\"github-link\">YourName</a></td> -->\n",
    "  </tr>\n",
    "</table>"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2024-03-02T14:10:23.417965Z",
     "start_time": "2024-03-02T14:10:20.268605Z"
    }
   },
   "source": [
    "%pip install aps-toolkit --upgrade"
   ],
   "outputs": []
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Auth"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2024-03-02T14:10:23.422282Z",
     "start_time": "2024-03-02T14:10:23.418981Z"
    }
   },
   "source": [
    "from aps_toolkit import Auth\n",
    "\n",
    "token = Auth().auth2leg()"
   ],
   "outputs": []
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Auth via Google Colab"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "source": [
    "# from aps_toolkit import Auth\n",
    "# from google.colab import userdata\n",
    "# client_id = userdata.get('APS_CLIENT_ID')\n",
    "# client_secret = userdata.get('APS_CLIENT_SECRET')\n",
    "# auth = Auth(client_id, client_secret)\n",
    "# token = auth.auth2leg()"
   ],
   "outputs": []
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Hubs"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "A Hub in Autodesk Forge is a container for projects. It represents a workspace for a team where they can collaborate on design and construction efforts. Hubs can be associated with BIM 360 Team, BIM 360 Docs, or A360. Each hub contains projects, and each project contains folders, items, and versions, which are used to manage and store design data."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2024-03-02T14:10:24.828033Z",
     "start_time": "2024-03-02T14:10:24.816616Z"
    }
   },
   "source": [
    "from aps_toolkit import BIM360\n",
    "\n",
    "bim360 = BIM360(token)"
   ],
   "outputs": []
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2024-03-02T14:10:25.834984Z",
     "start_time": "2024-03-02T14:10:24.829041Z"
    }
   },
   "source": [
    "hubs = bim360.get_hubs()\n",
    "hubs_id = hubs[\"data\"][0][\"id\"]\n",
    "hubs_id"
   ],
   "outputs": []
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "source": [
    "# batch generate all project from hub with projectId, projectName, and projectType,topFolderId\n",
    "df = bim360.batch_report_projects(hubs_id)\n",
    "# df[\"project_name\"] = \"XXXX\"\n",
    "df.head()"
   ],
   "outputs": []
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Projects"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "A Project in Autodesk Forge is a specific workspace within a Hub. It's where the actual design and construction data is stored. Each project contains folders, items, and versions. \n",
    "\n",
    "Folders are the organizational structure for the project. Items are specific design files, documents, or other types of data. Versions represent the different iterations of an item as it goes through the design and construction process. \n",
    "\n",
    "In summary, a project is a specific workspace for a team to collaborate on within a Hub in Autodesk Forge."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2024-03-02T14:10:27.016468Z",
     "start_time": "2024-03-02T14:10:25.835994Z"
    }
   },
   "source": [
    "projects = bim360.get_projects(hubs_id)\n",
    "projects_id = projects[\"data\"][0][\"id\"]\n",
    "projects_id"
   ],
   "outputs": []
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Folders\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "A Folder in Autodesk Platform Services(Former is Autodesk Forge) is part of the organizational structure within a Project. It's used to group and manage related Items, which can be design files, documents, or other types of data.\n",
    "\n",
    "Folders can contain sub-folders, creating a hierarchical structure that helps teams organize their work effectively. This structure can mirror the way teams organize their files on their local systems, making it easier to navigate and find specific items within a Project."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Get Top Folders"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2024-03-02T14:10:28.121907Z",
     "start_time": "2024-03-02T14:10:27.018657Z"
    }
   },
   "source": [
    "topfolders = bim360.get_top_folders(hubs_id, projects_id)\n",
    "topfolders_id = topfolders[\"data\"][0][\"id\"]\n",
    "topfolders_id"
   ],
   "outputs": []
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Items"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "An Item in Autodesk Forge represents a specific piece of data within a Project Folder. This could be a design file, a document, or any other type of data that is relevant to the project.\n",
    "\n",
    "Each item can have multiple versions, representing the different iterations of that item as it goes through the design and construction process. This allows for effective version control and tracking of changes over time.\n",
    "\n",
    "Items are the core unit of design data in Autodesk Forge. By accessing and manipulating items, users can work with the actual design data, view it in different ways, make changes, and collaborate with others."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Get Items By Folder"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2024-03-02T14:10:29.255473Z",
     "start_time": "2024-03-02T14:10:28.121907Z"
    }
   },
   "source": [
    "projects_id = \"b.1f7aa830-c6ef-48be-8a2d-bd554779e74b\"\n",
    "folderId = \"urn:adsk.wipprod:fs.folder:co.5ufH-U8yRjaZ-USJxxN_Mw\"\n",
    "\n",
    "contents = bim360.get_folder_contents(projects_id, folderId)\n",
    "itemId = contents[\"data\"][0][\"id\"]\n",
    "itemId"
   ],
   "outputs": []
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Get Item Name "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "source": [
    "item_name = bim360.get_item_display_name(projects_id, itemId)\n",
    "item_name"
   ],
   "outputs": []
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Get Item Infos"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "source": [
    "bim360.get_item_info(projects_id, itemId)"
   ],
   "outputs": []
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## URN"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In Autodesk Forge, a URN (Uniform Resource Name) is a unique identifier for a specific resource, such as a design file or version of a file. \n",
    "\n",
    "A derivative, on the other hand, is a representation of a design file in a different format. For example, a 3D model might have derivatives that are 2D drawings, thumbnail images, or files in different 3D formats. \n",
    "\n",
    "When you upload a design file to Autodesk Forge, it creates a URN for that file and generates derivatives. These derivatives are also associated with their own unique URNs. \n",
    "\n",
    "You can use these URNs to retrieve specific resources through the Forge APIs. For example, you might retrieve a derivative to display a 3D model in a web browser, or to download a 2D drawing. \n",
    "\n",
    "In summary, a URN derivative in Autodesk Forge is a unique identifier for a specific representation of a design file."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "source": [
    "urn = bim360.get_urn_item_version(projects_id, itemId, 2)\n",
    "print(f\"URN for item {itemId} with version 2 is:\\nURN:{urn}\")"
   ],
   "outputs": []
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Batch Report All Derivatives URN Version Item"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "metadata": {},
   "source": [
    "bim360.batch_report_item_versions(projects_id, itemId)"
   ],
   "outputs": []
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Congratulations! You've learned about the key concepts in Autodesk Forge, including Hubs, Projects, Folders, Items, and URNs. These concepts are the building blocks of the Autodesk Forge platform, and understanding them is crucial for working effectively with design data and collaborating with others."
   ]
  }
 ],
 "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.11.5"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}