Merge pull request #391 from ritza-co/docs-19.03.08

Docs 19.03.08 release (Week 47, 2024)

docs/administration/tags.mdx

@@ -0,0 +1,75 @@
+---
+title: "Tags"
+sidebar_position: 15
+---
+
+import ThemedImage from '@theme/ThemedImage'
+import useBaseUrl from '@docusaurus/useBaseUrl'
+
+Tags are useful for filtering and grouping objects. For example, you could define a "Project X" tag and associate that tag with all the devices, IP addresses, and other items associated with Project X.
+
+Most objects in Device42 can be tagged and most reports can be filtered according to tags.
+
+Navigate to the Tags list page under **Infrastructure > Organization > Tags** to view, edit, and create tags.
+
+<ThemedImage
+  alt="Tags list page"
+  sources={{
+    light: useBaseUrl('/assets/images/tags/list-page-light.png'),
+    dark: useBaseUrl('/assets/images/tags/list-page-dark.png'),
+  }}
+/>
+
+### Create Tags
+
+Click the **+ Add Tags** button to create a new tag. Tag names can contain spaces. The **Slug** is a unique resource identifier for each tag and is automatically filled in.
+
+You can also create new tags directly from an object or autodiscovery job configuration page, under the **Tags** field.
+
+<ThemedImage
+  alt="Add a new tag"
+  sources={{
+    light: useBaseUrl('/assets/images/tags/add-tag-light.png'),
+    dark: useBaseUrl('/assets/images/tags/add-tag-dark.png'),
+  }}
+  style={{ width: '50' }} 
+/>
+
+### View and Edit Tags
+
+On the Tags list page, you can click on a tag name to view the objects with that tag. To remove an association, click **Edit**, check the **Delete?** checkbox, and click **Save**.
+
+<ThemedImage
+  alt="Add a new tag"
+  sources={{
+    light: useBaseUrl('/assets/images/tags/tagged-items-light.png'),
+    dark: useBaseUrl('/assets/images/tags/tagged-items-dark.png'),
+  }}
+  style={{ width: '50' }} 
+/>
+
+### Tagging Objects
+
+Add a tag to a device by filling in the **Tag** field when creating or editing a device. You also specify tags for discovered objects when configuring an autodiscovery job. 
+
+<ThemedImage
+  alt="Tagging a device"
+  sources={{
+    light: useBaseUrl('/assets/images/tags/tagged-device-light.png'),
+    dark: useBaseUrl('/assets/images/tags/tagged-device-dark.png'),
+  }}
+/>
+
+### Merging Tags
+
+Due to misspellings or duplication, you may end up with multiple similar tags. You can merge them as follows:
+
+From the Tags list page, select two or more tags, choose **Merge selected tags** from the **Select an action** dropdown, and click the **hammer icon** to execute the merge. 
+
+<ThemedImage
+  alt="Merge action"
+  sources={{
+    light: useBaseUrl('/assets/images/tags/merge-tags-light.png'),
+    dark: useBaseUrl('/assets/images/tags/merge-tags-dark.png'),
+  }}
+/>

docs/getstarted/tutorials/index.md

@@ -2,14 +2,15 @@
 title: "Tutorials"
 ---
 
-Welcome to Device42! The tutorials in this section are designed to introduce you to the fundamentals of using the Device42 Main Appliance.
+Welcome to Device42! Explore the tutorials in this section to learn the fundamentals of using the Device42 Main Appliance (MA).
 
-Start with the [Introduction to Device42](/getstarted/tutorials/device42-tutorial.mdx) page for an explanation of Device42 terminology, object types, and the object hierarchical order. Read about the various ways you can add IT data to and export it from the Device42 Main Appliance.
+Start with the [Introduction to Device42](/getstarted/tutorials/device42-tutorial.mdx), which explains the terminology, object types, and object hierarchy used in Device42 and covers the various ways IT data can be added to and exported from the Device42 MA.
 
-Next, follow one or both of the tutorials below to add sample data to your new Device42 instance:
-- The [spreadsheets tutorial](getstarted/tutorials/tutorial-loading-data-using-spreadsheets.mdx) shows you how to access a sample `.xls` file, add data to it, and re-upload the file to load data to Device42.
-- The [API tutorial](getstarted/tutorials/tutorial-loading-data-using-the-api.mdx) introduces the Device42 API by executing a bash script of several curl commands that use APIs to load sample data.
+Next, learn how to add sample data to your new Device42 instance using either of the following:
 
-Complete your introduction with the [Device42 user interface tutorial](getstarted/tutorials/tutorial-navigating-the-device42-user-interface.mdx). Explore the sample data in the Device42 UI to get familiar with the menu options and data organization. 
+- The [spreadsheets tutorial](getstarted/tutorials/tutorial-loading-data-using-spreadsheets.mdx) shows you how to access and add data to a sample `.xls` file, then re-upload it to add the data to Device42.
+- The [API tutorial](getstarted/tutorials/tutorial-loading-data-using-the-api.mdx) demonstrates how to execute a bash script of several curl commands that call the Device42 API to add sample data to Device42.
 
-After completing the tutorials, have a look at the pages in the [Get Started](/getstarted/) section to discover more Device42 features. If you have any questions, comments, or feature requests, please let us know at [[email protected]](mailto:[email protected]).
+Complete your introduction with the [UI tutorial](getstarted/tutorials/tutorial-navigating-the-device42-user-interface.mdx). Explore the sample data in the Device42 UI to familiarize yourself with the menu options and data organization.
+
+Once you've completed the tutorials, you can discover more Device42 features in the rest of the [Get Started](/getstarted/) section. If you have any questions, comments, or feature requests, please let us know at [[email protected]](mailto:[email protected]).

docs/getstarted/tutorials/tutorial-loading-data-using-the-api.mdx

@@ -6,33 +6,38 @@ sidebar_position: 2
 import ThemedImage from '@theme/ThemedImage'
 import useBaseUrl from '@docusaurus/useBaseUrl'
 
-This tutorial will show you how to load sample data into the Device42 Main Appliance using the Device42 API. You don't need any prior programming knowledge and only need to execute a bash script of curl commands from the command prompt.
+This tutorial demonstrates how to load sample data into the Device42 Main Appliance (MA) using the Device42 API. You don't need any prior programming knowledge, only the ability to execute a bash script of curl commands from the command prompt.
 
 To run the script, you need a \*nix system with curl, a data transfer tool built into Linux and Ubuntu.
 
 ### Running the API Script
 
-1. Download the API script from the [Device42 automation scripts page](https://github.com/device42/demo-data-shell-scripts/blob/master/demo_script.sh). 
+1. Download the API script from the Device42 [automation scripts page](https://github.com/device42/demo-data-shell-scripts/blob/master/demo_script.sh) on GitHub. 
 
     ![GitHub download button](/assets/images/tutorial-loading-data-using-the-api/download-script.png)
 
-2. Open the script in a text editor like Windows Notepad or Ubuntu Gedit. Don't use a word processor like Microsoft Word. 
+2. Open the script in a text editor, like Windows Notepad or Ubuntu Gedit. Don't use a word processor like Microsoft Word.
 3. Add your credentials to lines 2-4 of the script. Replace `https://IP` with your Device42 IP address or FQDN, and supply your `username` and `password`:
+
     ```bash
     URL=https://IP
     USER='username'         
     PASS='password' 
     ```
+
 4. Open a Linux terminal and run the script by typing `sh` followed by the path and file name of the script. For example:
+
     ```bash
     $ sh /tmp/demo_script.sh
     ```
-    You will see information displayed in the terminal as the script executes and each curl statement outputs a success message. 
-5. Now log in to your Device42 Main Appliance. 
 
-Running the script adds sample data including a building, two rooms, six vendors, four racks, seven devices, and three customers to your Main Appliance. You'll see statistics of the additions on your dashboard, depending on your settings. Some data like custom keys and value pairs aren't displayed in the dashboard, but you'll see them when browsing the data in the system.
+    You will see information displayed in the terminal as the script executes and each curl statement outputs a success message.
 
-You can view data added for an object category by navigating to that category's list page from the main menu. For example, if you go to **Resources > All Devices** you'll see the newly created records with names beginning with "nh-demo-".
+5. Log in to your Device42 MA.
+
+Running the script adds sample data – including a building, two rooms, six vendors, four racks, seven devices, and three customers – to your MA. Depending on your settings, you may see statistics for these additions on your dashboard. Some data isn't displayed in the dashboard, but can be found by browsing the system (for example, data concerning custom keys and value pairs).
+
+You can view data added for an object category by navigating to the list page for that category from the main menu. For example, if you go to **Resources > All Devices**, you'll see the newly created records with names beginning with `nh-demo-`.
 
 <ThemedImage
   alt="New devices added on the list page"
@@ -44,9 +49,9 @@ You can view data added for an object category by navigating to that category's
 
 ### Understanding the API Script
 
-Now, let's look at one of the curl statements you just executed. If you are sure that you will never use curl and the Device42 API, you can safely skip this section. 
+Now, let's look at one of the curl statements you just executed. If you are sure that you will never use curl and the Device42 API, you can safely skip this section.
 
-Each line in the script has a curl statement like the one below. Note that the `\` backslashes aren't in the original script and are used here to continue the command on a new line for readability.
+Each line in the script has a curl statement like the one below. Note that the backslashes (`\`) aren't in the original script and are used here to continue the command on a new line for readability.
 
 ```bash
 #Add a Building
@@ -63,48 +68,51 @@ curl -i -H "Accept: application/json" \
 ```
 
 The `-i`, `-H`, and `--insecure` parameters should be in all Device42 API calls:
-- The `-i` flag specifies that the header should be included in the output. 
-- The `-H` flag tells the Device42 application that a JSON-formatted response will be accepted. 
-- The `--insecure` flag is required because the Device42 appliance does not have a certificate. 
+
+- The `-i` flag specifies that the header should be included in the output.
+- The `-H` flag tells the Device42 application that a JSON-formatted response will be accepted.
+- The `--insecure` flag is required because the Device42 appliance does not have a certificate.
 
 The values of the following flags and variables vary depending on the API used:
-- The `-X` value specifies the HTTP method used. 
-- The `-d` values are object category parameters. For example, a building has the `address=` parameter as an optional field to fill in.
+
+- The `-X` value specifies the HTTP method used.
+- The `-d` values are object category parameters. For example, a building has the `address=` parameter as an optional fillable field.
 - The `URL` value is the API endpoint. For example, `/api/1.0/buildings/` is the endpoint for the building object category.
 
-Watch our videos on using API imports to [create hardware models](how-to-videos/api-imports-add-create-hardware-models.md) or [add devices to racks](how-to-videos/api-imports-adding-devices-to-racks.md) for guided examples.
+Watch our videos for guided examples of how to use API imports to [create hardware models](how-to-videos/api-imports-add-create-hardware-models.md) or [add devices to racks](how-to-videos/api-imports-adding-devices-to-racks.md).
 
 ## The API Documentation
 
-The [Device42 API website](https://api.device42.com/) is a resource to find information on the API endpoints you need to get data from or add data to Device42. 
+The [Device42 API website](https://api.device42.com/) serves as a resource for information about the API endpoint needed to get data to and from Device42.
 
-The documentation for this API command tells you that the `-X` value should be `POST` and the `URL` endpoint is `/api/1.0/buildings/`. Under the "Parameters" section, you'll see a `name` value is required and that `address` is an option. 
+The documentation for the above API command tells you that the `-X` value should be `POST` and the `URL` endpoint is `/api/1.0/buildings/`. Under the **Parameters** section, you can see that a `name` value is required and that `address` is an option.
 
 ![API docs buildings](/assets/images//tutorial-loading-data-using-the-api/api-docs-buildings.png)
 
-### Finding Unique IDs 
+### Finding Unique IDs
 
-Some API parameters use unique IDs of other configuration items. For example, if you are creating a rack and want to specify the room the rack is in, you can find the unique ID of the room. This is especially useful if you have multiple rooms with the same name and want to specify one of them.
+Some API parameters use the unique IDs of other Configuration Items (CIs). For example, if you create a rack and want to specify the room where the rack is stored, you can find the unique ID for that room. This is especially useful if you have multiple rooms with the same name and want to specify one of them.
 
-This is the documentation for the **Create/update** racks API with the optional `room_id` parameter highlighted. 
+The following screenshot shows the documentation for the **Create/update** racks API, highlighting the optional `room_id` parameter.
 
 ![API docs buildings](/assets/images//tutorial-loading-data-using-the-api/racks-api-paramaters.png)
 
-There are two ways to get an ID. First, you can do it programmatically using the endpoint for the object, like `/api.1.0/rooms/`. This method is most appropriate for a more complex program written in Java or Python. 
+You can get an ID one of two ways:
 
-If you are executing curl commands in a shell script, do the following: From the Main Appliance, go to **Infrastructure > DataCenter > Rooms**. Then, hover over the name of the room for which you wish to find the ID.
+- You can use the endpoint for the object (for example, `/api.1.0/rooms/`) to get it programmatically. This method is most appropriate for a more complex program written in Java or Python.
+- If you are executing curl commands in a shell script, you can open the MA, go to **Infrastructure > DataCenter > Rooms**, and hover over a room name to view its URL in the lower left corner of your screen. The last number in the URL is the unique ID
 
-<ThemedImage
-  alt="Hover over room name"
-  sources={{
-    light: useBaseUrl('/assets/images/tutorial-loading-data-using-the-api/hover-room-light.png'),
-    dark: useBaseUrl('/assets/images/tutorial-loading-data-using-the-api/hover-room-dark.png'),
-  }}
-  style={{ width: '60%' }} 
-/>
+  <ThemedImage
+    alt="Hover over room name"
+    sources={{
+      light: useBaseUrl('/assets/images/tutorial-loading-data-using-the-api/hover-room-light.png'),
+      dark: useBaseUrl('/assets/images/tutorial-loading-data-using-the-api/hover-room-dark.png'),
+    }}
+    style={{ width: '60%' }} 
+  />
 
-For example, hover over the "IDF2" hyperlink, and look at the lower left corner of your screen to see the small URL of the room. The unique ID is the last number in the URL, which is "26". 
+  For example: If you hover over the **DF2** hyperlink, you'll see that the last number in the URL is `26`. This is its unique ID.
 
 ## Next Steps
 
-Next, we encourage you to follow the [Navigating the Device42 User Interface](/getstarted/tutorials/tutorial-navigating-the-device42-user-interface.mdx) tutorial. Browse through the documentation for more detailed information on the various Device42 features.
+Next, we encourage you to follow the [Device42 UI](/getstarted/tutorials/tutorial-navigating-the-device42-user-interface.mdx) tutorial. Browse through the documentation for more detailed information on the various Device42 features.