Merge pull request #829 from JupiterOne/add-docs-table-of-contents

Nick-NCSU · web-flow · commit cd93056d38fa · 2023-01-25T11:57:41.000-05:00
Add table of contents to integration docs
diff --git a/docs/integrations/development.md b/docs/integrations/development.md
@@ -8,6 +8,94 @@ state of the world" from a provider and have the data sent to JupiterOne. Data
 that was sent up will be diffed against JupiterOne's understanding of the
 "world" and persisted via a background process.
 
+## Table of Contents
+
+- [Integration development](#integration-development)
+  - [Table of Contents](#table-of-contents)
+  - [The integration framework](#the-integration-framework)
+    - [`IntegrationInvocationConfig` fields](#integrationinvocationconfig-fields)
+      - [`instanceConfigFields`](#instanceconfigfields)
+      - [`loadExecutionConfig`](#loadexecutionconfig)
+      - [`validateInvocation`](#validateinvocation)
+      - [`getStepStartStates`](#getstepstartstates)
+      - [`integrationSteps`](#integrationsteps)
+      - [`beforeAddEntity(context: IntegrationExecutionContext<IntegrationConfig>, e: Entity): Entity`](#beforeaddentitycontext-integrationexecutioncontextintegrationconfig-e-entity-entity)
+      - [`beforeAddRelationship(context: IntegrationExecutionContext<IntegrationConfig>, r: Relationship): Promise<Relationship> | Relationship`](#beforeaddrelationshipcontext-integrationexecutioncontextintegrationconfig-r-relationship-promiserelationship--relationship)
+    - [How integrations are executed](#how-integrations-are-executed)
+      - [Validation](#validation)
+      - [Collection](#collection)
+    - [What's in the `IntegrationExecutionContext` and `IntegrationExecutionStepContext`?](#whats-in-the-integrationexecutioncontext-and-integrationexecutionstepcontext)
+      - [`IntegrationExecutionContext`](#integrationexecutioncontext)
+        - [`instance`](#instance)
+        - [`logger`](#logger)
+          - [`forbiddenResource`](#forbiddenresource)
+      - [`IntegrationExecutionStepContext`](#integrationexecutionstepcontext)
+        - [`jobState`](#jobstate)
+    - [Additional utilities](#additional-utilities)
+      - [Data conversion](#data-conversion)
+      - [Graph data generation and validation](#graph-data-generation-and-validation)
+        - [`createIntegrationEntity`](#createintegrationentity)
+        - [`createDirectRelationship`](#createdirectrelationship)
+          - [`DirectRelationshipOptions`](#directrelationshipoptions)
+          - [`DirectRelationshipLiteralOptions`](#directrelationshipliteraloptions)
+        - [`createMappedRelationship`](#createmappedrelationship)
+          - [`MappedRelationshipOptions`](#mappedrelationshipoptions)
+          - [`MappedRelationshipLiteralOptions`](#mappedrelationshipliteraloptions)
+      - [Raw data collection](#raw-data-collection)
+      - [Testing](#testing)
+    - [Auto-magic behind the framework](#auto-magic-behind-the-framework)
+      - [Event reporting](#event-reporting)
+      - [Data collection](#data-collection)
+      - [Failure handling](#failure-handling)
+        - [Step status codes](#step-status-codes)
+      - [Letting the synchronizer know about partial datasets](#letting-the-synchronizer-know-about-partial-datasets)
+        - [Detecting undeclared types](#detecting-undeclared-types)
+  - [The CLI](#the-cli)
+    - [Authentication](#authentication)
+    - [Supported commands](#supported-commands)
+      - [Command `j1-integration collect`](#command-j1-integration-collect)
+        - [Options](#options)
+          - [Option `--module` or `-m`](#option---module-or--m)
+          - [Option `--integrationInstanceId` or `-i`](#option---integrationinstanceid-or--i)
+          - [Option `--api-key` or `-k`](#option---api-key-or--k)
+          - [Option `--step` or `-s`](#option---step-or--s)
+          - [Option `--no-cache`](#option---no-cache)
+          - [Option `--cache-path`](#option---cache-path)
+          - [Option `--disable-schema-validation` or `-V`](#option---disable-schema-validation-or--v)
+      - [Command `j1-integration sync`](#command-j1-integration-sync)
+        - [Keeping the door open for developers not using JavaScript or TypeScript](#keeping-the-door-open-for-developers-not-using-javascript-or-typescript)
+        - [Options](#options-1)
+          - [Option `--module` or `-m`](#option---module-or--m-1)
+          - [Option `--integrationInstanceId` or `-i`](#option---integrationinstanceid-or--i-1)
+          - [Option `--source`](#option---source)
+          - [Option `--scope`](#option---scope)
+          - [Option `--api-key` or `-k`](#option---api-key-or--k-1)
+          - [Option `--tail` or `-t`](#option---tail-or--t)
+          - [Option `--api-base-url`](#option---api-base-url)
+      - [Command `j1-integration run`](#command-j1-integration-run)
+        - [Option `--skip-finalize`](#option---skip-finalize)
+      - [Command `j1-integration visualize`](#command-j1-integration-visualize)
+      - [Command `j1-integration visualize-types`](#command-j1-integration-visualize-types)
+      - [Command `j1-integration document`](#command-j1-integration-document)
+      - [Command `j1-integration validate-question-file`](#command-j1-integration-validate-question-file)
+      - [Command `j1-integration generate-integration-graph-schema`](#command-j1-integration-generate-integration-graph-schema)
+      - [Future commands and utilities](#future-commands-and-utilities)
+        - [More commands and options](#more-commands-and-options)
+          - [Command `j1-integration plan`](#command-j1-integration-plan)
+          - [Command `j1-integration sync --dry-run`](#command-j1-integration-sync---dry-run)
+          - [Command `j1-integration generate`](#command-j1-integration-generate)
+        - [One CLI tool for all JupiterOne development](#one-cli-tool-for-all-jupiterone-development)
+        - [Better methods of authentication with JupiterOne](#better-methods-of-authentication-with-jupiterone)
+  - [Does JupiterOne use this SDK for managed integrations?](#does-jupiterone-use-this-sdk-for-managed-integrations)
+  - [Future work around integrations](#future-work-around-integrations)
+    - [`external` integrations](#external-integrations)
+    - [Event ingestion](#event-ingestion)
+  - [j1 CLI](#j1-cli)
+    - [Authentication](#authentication-1)
+    - [Supported commands](#supported-commands-1)
+      - [Command `j1 export`](#command-j1-export)
+      - [Command `j1 import`](#command-j1-import)
+
 ## The integration framework
 
 This SDK supports building JupiterOne integrations using either JavaScript or
diff --git a/docs/integrations/development_guide.md b/docs/integrations/development_guide.md
@@ -8,24 +8,26 @@ in this SDK project.
 
 ## Table of Contents
 
-- [Getting Started](#getting-started)
-  - [Requirements](#requirements)
-  - [Setup](#setup)
-- [Developing the integration](#developing-the-integration)
-  - [Integration Configuration](#integration-configuration)
-  - [Creating instanceConfigFields](#1-creating-instanceconfigfields)
-  - [Creating validateInvocation](#2-creating-validateinvocation)
-    - [Adding or creating an API Client](#adding-or-creating-an-api-client)
-      - [Basic client setup](#basic-client-setup)
-      - [Adding the first route](#adding-the-first-route)
-  - [Creating your first IntegrationStep](#3-creating-your-first-integrationstep)
-    - [Creating the Account step](#creating-the-account-step)
-      - [id](#id)
-      - [name](#name)
-      - [entities](#entities)
-      - [executionHandler](#executionhandler)
-        - [Converters](#converters)
-  - [Running the integration](#running-the-integration-🚀)
+- [Getting Started with Integration Development](#getting-started-with-integration-development)
+  - [Table of Contents](#table-of-contents)
+  - [Getting Started](#getting-started)
+    - [**Requirements**](#requirements)
+    - [**Setup**](#setup)
+  - [**Developing the integration**](#developing-the-integration)
+    - [**Integration configuration**](#integration-configuration)
+    - [**1. Creating `InstanceConfigFields`**](#1-creating-instanceconfigfields)
+    - [**2. Creating `ValidateInvocation`**](#2-creating-validateinvocation)
+    - [Adding or Creating an API Client](#adding-or-creating-an-api-client)
+    - [Basic Client Setup](#basic-client-setup)
+    - [Adding the first route](#adding-the-first-route)
+    - [**3. Creating your first `IntegrationStep`**](#3-creating-your-first-integrationstep)
+      - [**Creating the `Account` Step**](#creating-the-account-step)
+      - [**id**](#id)
+      - [**name**](#name)
+      - [**entities**](#entities)
+    - [**executionHandler**](#executionhandler)
+      - [**Converters**](#converters)
+  - [Running the integration](#running-the-integration)
 
 ## Getting Started
 
@@ -699,7 +701,7 @@ export async function fetchAccountDetails({
 
 And that's it! We have a working `executionHandler`.
 
-## Running the integration 🚀
+## Running the integration
 
 We've now:
 
diff --git a/docs/integrations/step-patterns.md b/docs/integrations/step-patterns.md
@@ -14,6 +14,20 @@ JupiterOne integration. Here, we assign names to each of these patterns in order
 to build a shared, referenceable grammar to use when developing new JupiterOne
 integrations.
 
+## Table of Contents
+
+- [JupiterOne Integration Step Patterns](#jupiterone-integration-step-patterns)
+  - [Table of Contents](#table-of-contents)
+  - [Step Classification](#step-classification)
+  - ["Singleton" step pattern](#singleton-step-pattern)
+  - ["Fetch Entities" step pattern](#fetch-entities-step-pattern)
+  - ["Fetch Relationships" step pattern](#fetch-relationships-step-pattern)
+  - ["Fetch Child Entities" step pattern](#fetch-child-entities-step-pattern)
+  - ["Build Child Relationships" step pattern](#build-child-relationships-step-pattern)
+  - [Conclusion](#conclusion)
+
+## Step Classification
+
 Let's imagine a JupiterOne integration for a device management tool, "Acme".
 This integration ingests the following entities and relationships:
 
diff --git a/docs/integrations/testing.md b/docs/integrations/testing.md
@@ -32,6 +32,16 @@ fetched. Steps iterate source objects using the data client and converters to
 produce entities and relationships, but the steps are responsible for organizing
 data collection and entity and relationship construction.
 
+## Table of Contents
+
+- [Testing Integrations](#testing-integrations)
+  - [Table of Contents](#table-of-contents)
+  - [Integration Testing](#integration-testing)
+  - [Unit Testing](#unit-testing)
+    - [`createMockExecutionContext`](#createmockexecutioncontext)
+      - [Testing steps using `executeStepWithDependencies`](#testing-steps-using-executestepwithdependencies)
+      - [`setupRecording`](#setuprecording)
+
 ## Integration Testing
 
 Ideal integration testing (ensuring end-to-end success) would:
