added some hyperlinks and markdown format updates

Author: jyaistMap

guide/13-managing-arcgis-applications/itemgraph_and_remap_data.ipynb

@@ -1,5 +1,21 @@
 {
  "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "d001bd9c-9c51-465f-8f4c-3e5b70a791d5",
+   "metadata": {},
+   "source": [
+    "# Working with Item Dependencies and Data Sources"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "25fe73d4-40ed-41af-adcc-8dd97479a1ce",
+   "metadata": {},
+   "source": [
+    "## Introduction"
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": 1,
@@ -19,47 +35,49 @@
    "id": "9c6bf122-1555-4798-adbe-706ad2dd89dc",
    "metadata": {},
    "source": [
-    "# Working with Item Dependencies and Data Sources\n",
-    "\n",
-    "Versions 2.4.0 and 2.4.1 of the ArcGIS API for Python introduced some very handy functionality for content management workflows: the `arcgis.apps.itemgraph` module and the `item.remap_data()` function. This functionality was added with a set of goals in mind: to give users the ability to understand what their org items need to exist, understand how the org items relate to one another, and easily fix org items with faulty components.\n",
+    "Versions 2.4.0 and 2.4.1 of the ArcGIS API for Python introduced some very handy functionality for content management workflows: the [`arcgis.apps.itemgraph`](/python/latest/api-reference/arcgis.apps.itemgraph.html) module and the [`item.remap_data()`](/python/latest/api-reference/arcgis.gis.toc.html#arcgis.gis.Item.remap_data) function. The primary goals of this added functionality: \n",
+    "* provide the ability to understand what organizational items need in order to exist\n",
+    "* understand how organizational items relate to one another\n",
+    "* update organizational items with invalid components\n",
     "\n",
-    "The `itemgraph` module helps us accomplish these first two goals. The classes and functions in this module allow a user to create a directional graph documenting the relationships between different items in an org- start with a root item, and you'll be able to see all of the items it needs to exist, all of the items that those items then need to exist, and so on. \n",
+    "The [`itemgraph`](/python/latest/api-reference/arcgis.apps.itemgraph.html) module accomplishes these first two goals. The classes and functions in this module allow a user to create a directional graph documenting the relationships between different items in an organization- starting with a root item, you'll be able to see all of the items it needs to exist, all of the items that those items need to exist, and so on. \n",
     "\n",
-    "`remap_data()` helps us accomplish the third goal. Say you have a complex application- once you know an item's dependencies, you can easily change or fix one. Additionally, if you have knowledge of the structure of your app, you can use this function to fix other components of it as well.\n",
+    "The [`remap_data()`](/python/latest/api-reference/arcgis.gis.toc.html#arcgis.gis.Item.remap_data) method accomplishes the third goal. Say you have a complex application- once you know an item's dependencies, you can easily change or fix one. Additionally, if you have knowledge of the structure of your app, you can use this function to fix other components of it as well.\n",
     "\n",
-    "Using these two things in conjunction with one another is a powerful combination, and we'll go over a basic but important workflow that leverages both of them.\n",
+    "Using these functions and methods in conjunction is a powerful combination, and we'll go over a basic but important workflow that leverages both of them.\n",
     "\n",
     "## The `arcgis.apps.itemgraph` Module\n",
     "\n",
     "### What is a Dependency?\n",
     "\n",
-    "We'll start by examining 2 classes and a function that center around a core concept: creating a dependency graph that allows users to examine how items relate to eachother in their ArcGIS Online or Enterprise organizations. As mentioned above, these graphs inform us what items are required for other items to exist, and encompass the full range of dependency types for items. \n",
+    "We'll start by examining 2 classes and a function that center around a core concept: creating a dependency graph that allows users to examine how items relate to each other in their ArcGIS Online or Enterprise organizations. As mentioned above, these graphs inform us what items are required for other items to exist, and encompass the full range of dependency types for items. \n",
     "\n",
-    "Before we dive a bit deeper into it, let's briefly go over a handful of the ways an item can be part of another item. There are tons of different item types in the ArcGIS universe, and the ways they all store and use data vary greatly; some are based on JSON structures, some are based on hosted services, and others on a variety of common (or uncommon) file types. Items can use other items in a wide range of ways, such as:\n",
+    "Before we dive a bit deeper into it, let's briefly go over a handful of the ways an item can be part of another item. There are many different [item types](/rest/users-groups-and-items/items-and-item-types/) in the ArcGIS universe, and the ways they store and use data vary greatly; some are based on JSON structures, some are based on hosted services, and others on a variety of common (or uncommon) file types. Items can use other items in a wide range of ways, such as:\n",
     "- source files for published layers (e.g., File GDB -> Feature Layer)\n",
     "- visual components in a web-based app (e.g., a Web Map found in a StoryMap)\n",
     "- attachments to other items (e.g., a Microsoft Word template in a Survey123 application)\n",
     "\n",
     "### Class Breakdown\n",
     "\n",
-    "[The documentation for the module can be found here](https://developers.arcgis.com/python/latest/api-reference/arcgis.apps.itemgraph.html).\n",
+    "[The documentation for the module can be found here](/python/latest/api-reference/arcgis.apps.itemgraph.html).\n",
     "\n",
     "Let's break down the 4 things we see in the doc:\n",
-    "#### - `ItemGraph`:\n",
+    "\n",
+    "#### [`ItemGraph`](/python/latest/api-reference/arcgis.apps.itemgraph.html#itemgraph)\n",
     "  \n",
     "The `ItemGraph` is the main structure that a user will be working with. It is built on top of [NetworkX's DiGraph class](https://networkx.org/documentation/stable/reference/classes/digraph.html), meaning it also gets access to all of NetworkX's DiGraph and Graph functionality. An `ItemGraph` is populated with instances of `ItemNode`, and can be created from scratch via `create_dependency_graph()` or from a priorly saved `ItemGraph` via `load_from_file`.\n",
     "\n",
-    "#### - `ItemNode`:\n",
+    "#### [`ItemNode`](/python/latest/api-reference/arcgis.apps.itemgraph.html#itemnode)\n",
     "\n",
-    "  An `ItemNode` is an object that pertains to an indexed item/dependency. The node's `.id` property is an item's id, or a service's url. In the case of nodes with a valid `Item` object in the org tied to the item id, that `Item` object will be stored as the node's `.item` property. The `ItemNode` class has functions on it that allow a user to see an item's dependencies stored in the graph going in either direction, initial-level or recursive.\n",
+    "An `ItemNode` is an object that pertains to an indexed item/dependency. The node's `.id` property is an item's id, or a service's url. In the case of nodes with a valid `Item` object in the org tied to the item id, that [`Item`](/python/latest/api-reference/arcgis.gis.toc.html#item) object will be stored as the node's `.item` property. The `ItemNode` class has functions on it that allow a user to see an item's dependencies stored in the graph going in either direction, initial-level or recursive.\n",
     "\n",
-    "#### - `create_dependency_graph()`:\n",
+    "#### [`create_dependency_graph()`](/python/latest/api-reference/arcgis.apps.itemgraph.html#create-dependency-graph)\n",
     "\n",
-    "  This is the main function that a user will use to construct an `ItemGraph`. Users feed in a list of `Item` objects or item id/url strings, and the function will recursively dissect any items or dependent items found and add everything to one `ItemGraph` returned back to a user. Users have the option to include items referenced from outside organizations in their graph, but these outside org items will not be explored for further dependencies. Additionally, for certain items that have reverse dependencies documented through their `related_items()` function, users have the option to include those in the graph as well.\n",
+    "This is the main function that a user will use to construct an `ItemGraph`. Users feed in a list of `Item` objects or item id/url strings, and the function will recursively dissect any items or dependent items found and add everything to one `ItemGraph` returned back to a user. Users have the option to include items referenced from outside organizations in their graph, but these outside org items will not be explored for further dependencies. Additionally, for certain items that have reverse dependencies documented through their [`related_items()`](/python/latest/api-reference/arcgis.gis.toc.html#arcgis.gis.Item.related_items) function, users have the option to include those in the graph as well.\n",
     "\n",
-    "#### - `load_from_file()`:\n",
+    "#### [`load_from_file()`](/python/latest/api-reference/arcgis.apps.itemgraph.html#load-from-file)\n",
     "\n",
-    "This is the alternative way to create an `ItemGraph`. When working with a graph, users have the option to write it out to a saved GML file format via `ItemGraph.write_to_file()`. GML is a format commonly used for saving/loading graphs between graphing libraries. Passing in an `ItemGraph` GML file to this function will reconstruct a graph with the same ID's and relationships. Users have the option to populate each `ItemNode` with item objects, or leave them strictly with ID's/relationships for the sake of performance (which is good when loading in a graph with thousands of items). We won't cover this function in this guide, but please refer to this guide(add link) for an advanced workflow demonstrating it.\n",
+    "This is the alternative way to create an `ItemGraph`. When working with a graph, users have the option to write it out to a saved [GML file format](https://networkx.org/documentation/stable/reference/readwrite/gml.html) via the [`write_to_file()`](/python/latest/api-reference/arcgis.apps.itemgraph.html#arcgis.apps.itemgraph.ItemGraph.write_to_file) method. GML is a format commonly used for saving/loading graphs between graphing libraries. Passing in an `ItemGraph` GML file to this function will reconstruct a graph with the same ID's and relationships. Users have the option to populate each `ItemNode` with item objects, or leave them strictly with ID's/relationships for the sake of performance (which is good when loading in a graph with thousands of items). We won't cover this function in this guide, but please refer to this [sample](/python/lateste/samples/org-wide-dependency-graph) for an advanced workflow demonstrating it.\n",
     "\n",
     "Now that we know the basics of the code, let's jump into it. We'll use `create_dependency_graph()` to create an `ItemGraph`, then examine  `ItemNode` instances in the graph to learn what our org items contain, are contained by, require to exist, and are required by to exist. We'll start with a Survey123 item."
    ]
@@ -94,7 +112,7 @@
    "id": "da409930-f779-44b8-982b-305f146ef6d9",
    "metadata": {},
    "source": [
-    "Calling `ItemGraph.all_items()` lets a user see all of the items in the graph. One important thing to note: with this function, as well as the `ItemNode` functions that return dependencies, a user can elect to return the items in \"item\" form, \"id\" form, or \"node\" form (the default)."
+    "Calling [`ItemGraph.all_items()`](/python/latest/api-reference/arcgis.apps.itemgraph.html#arcgis.apps.itemgraph.ItemGraph.all_items) lets a user see all of the items in the graph. One important thing to note: with this function, as well as the `ItemNode` functions that return dependencies, a user can elect to return the items in \"item\" form, \"id\" form, or \"node\" form (the default) by specifiying and `out_format` agrument:"
    ]
   },
   {
@@ -122,15 +140,15 @@
     }
    ],
    "source": [
-    "graph.all_items(\"item\")"
+    "graph.all_items(out_format=\"item\")"
    ]
   },
   {
    "cell_type": "markdown",
    "id": "4fa16c48-193c-4326-b3c1-3694e6a18f9d",
    "metadata": {},
    "source": [
-    "Let's grab and inspect an `ItemNode` instance by calling `ItemGraph.get_node()`."
+    "Let's grab and inspect an `ItemNode` instance by calling the [`ItemGraph.get_node()`](/python/latest/api-reference/arcgis.apps.itemgraph.html#arcgis.apps.itemgraph.ItemGraph.get_node) method."
    ]
   },
   {
@@ -352,7 +370,7 @@
    "id": "fd1761f6-ef27-4201-b11d-a43bf1414c81",
    "metadata": {},
    "source": [
-    "An important thing to remember is that `create_dependency_graph()` finds relationships from the top down, so `contained_by()` and `required_by()` will only show items that have been analyzed along the way from our root node(s)- they're not a full picture of _every_ item in the organization that may contain or require a specific item, just the ones contained under the umbrella of our original items. However, `contains()` and `requires()` do indeed show every item in an org that are contained or required by a given item.\n",
+    "An important thing to remember is that `create_dependency_graph()` finds relationships from the top down, so [`contained_by()`](/python/latest/api-reference/arcgis.apps.itemgraph.html#arcgis.apps.itemgraph.ItemNode.contained_by) and [`required_by()`](/python/latest/api-reference/arcgis.apps.itemgraph.html#arcgis.apps.itemgraph.ItemNode.required_by) will only show items that have been analyzed along the way from our root node(s)- they're not a full picture of _every_ item in the organization that may contain or require a specific item, just the ones contained under the umbrella of our original item. However, [`contains()`](/python/latest/api-reference/arcgis.apps.itemgraph.html#arcgis.apps.itemgraph.ItemNode.contains) and [`requires()`](/python/latest/api-reference/arcgis.apps.itemgraph.html#arcgis.apps.itemgraph.ItemNode.requires) do indeed show every item in an org that are contained or required by a given item.\n",
     "\n",
     "To get the full, org-wide picture with `contained_by()` or `required_by()`, a graph would need to be made with every item in the organization. See this sample(insert link) for a guide on how to create and manage that type of graph."
    ]
@@ -973,7 +991,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.11.10"
+   "version": "3.13.2"
   }
  },
  "nbformat": 4,