Merge pull request #347 from ritza-co/docs-19.01.4

Docs 19.01.4 release (Week 28, 2024)

docs/auto-discovery/enrichai-data/index.md

@@ -120,6 +120,8 @@ Please make sure the following is in place to ensure connectivity with EnrichAI:
    - `https://enrichai.device42.io/api/normalizations`
 3. Register the license online.
 
+[DOQL AI](/reports/device42-doql/doql-ai.mdx) generates queries based on natural language prompts you provide. Entered prompts are sent to the endpoint `ai42.device42.io`.
+
 ## Using the EnrichAI Interface
 
 Select **Analytics > EnrichAI Data** to display the EnrichAI Data list page.

docs/getstarted/tutorials/index.md

@@ -2,13 +2,14 @@
 title: "Tutorials"
 ---
 
-Welcome to the Device42 tutorials section. Choose a topic below to get started!
-
+Welcome to Device42! The tutorials in this section are designed to introduce you to the fundamentals of using the Device42 Main Appliance.
 
+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.
 
-## Table of contents
+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.
 
-- [Tutorials Overview](/getstarted/tutorials/device42-tutorial.mdx)
-- [Tutorial:  Loading Data Using Spreadsheets](getstarted/tutorials/tutorial-loading-data-using-spreadsheets.mdx)
-- [Tutorial:  Loading Data using the API](getstarted/tutorials/tutorial-loading-data-using-the-api.md)
-- [Tutorial:  Navigating the Device42 User Interface](getstarted/tutorials/tutorial-navigating-the-device42-user-interface.mdx)
+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. 
+
+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]).

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

@@ -0,0 +1,110 @@
+---
+title: "Tutorial: Loading Data Using the API"
+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.
+
+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). 
+
+    ![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. 
+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 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-".
+
+<ThemedImage
+  alt="New devices added on the list page"
+  sources={{
+    light: useBaseUrl('/assets/images/tutorial-loading-data-using-the-api/added-devices-light.png'),
+    dark: useBaseUrl('/assets/images/tutorial-loading-data-using-the-api/added-devices-dark.png'),
+  }}
+/>
+
+### 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. 
+
+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
+curl -i -H "Accept: application/json" \
+     -X POST \
+     -d "name=New Haven DC" \
+     -d "address=123 main st" \
+     -d "contact_name=roger" \
+     -d "contact_phone=1234567890" \
+     -d "notes=super critical" \
+     -u $USER:$PASS \
+     $URL/api/1.0/buildings/ \
+     --insecure
+```
+
+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 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 `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.
+
+## 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 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. 
+
+![API docs buildings](/assets/images//tutorial-loading-data-using-the-api/api-docs-buildings.png)
+
+### 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.
+
+This is the documentation for the **Create/update** racks API with the optional `room_id` parameter highlighted. 
+
+![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. 
+
+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.
+
+<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". 
+
+## 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.

docs/getstarted/tutorials/tutorial-navigating-the-device42-user-interface.mdx

@@ -8,7 +8,7 @@ import useBaseUrl from '@docusaurus/useBaseUrl'
 
 ## Prerequisites
 
-This tutorial uses sample data added to the Main Appliance from the [API tutorial](getstarted/tutorials/tutorial-loading-data-using-the-api.md). You can still follow along if you have at least one building record that includes a room with related rack CIs (Configuration Objects).
+This tutorial uses sample data added to the Main Appliance from the [API tutorial](getstarted/tutorials/tutorial-loading-data-using-the-api.mdx). You can still follow along if you have at least one building record that includes a room with related rack CIs (Configuration Objects).
 
 ## Dashboard View
 
@@ -22,7 +22,7 @@ On the home page of the Main Appliance, you'll see your dashboard below the noti
     }}
 />
 
-If you've followed the [spreadsheets tutorial](/getstarted/tutorials/device42-tutorial.mdx), [API tutorial](getstarted/tutorials/tutorial-loading-data-using-the-api.md), or run an autodiscovery job, your dashboard statistics will reflect the new CIs. 
+If you've followed the [spreadsheets tutorial](/getstarted/tutorials/device42-tutorial.mdx), [API tutorial](getstarted/tutorials/tutorial-loading-data-using-the-api.mdx), or run an autodiscovery job, your dashboard statistics will reflect the new CIs. 
 
 <ThemedImage
     alt="Classic Dashboard list view link"

docs/integration/external-integrations/jira-integrations/device42-jira-assets-integration.mdx

@@ -87,7 +87,7 @@ Copy the Device42 "Verification Token" from the external integration you just cr
 
 Go to the **Apps** tab in Jira and search for "Device42". Select the [Device42 for Jira Service Management Assets](https://marketplace.atlassian.com/search?query=device42) app and click on the yellow **Get app** button. 
 
-Next, open the Device42 JSM Assets app and configure it by clicking on the **Settings** tab. In the "Device42 Cloud Connector" field type in `connect.device42.io`. Paste the verification token that you copied from the Device42 external integration into the "Device42 Verification Token" field. Click on the **Save** button. 
+Next, open the Device42 Insight Connect app and configure it by clicking on the **Settings** tab. In the "Device42 Cloud Connector" field type in `connect.device42.io`. Paste the verification token that you copied from the Device42 external integration into the "Device42 Verification Token" field. Click on the **Save** button. 
 
 ![JSM Device42 app settings](/assets/images/jsm-assets-integration/jira-d42-app-settings.png)