From d3ca54c1a7fe53dd634e66c8f95607b921060783 Mon Sep 17 00:00:00 2001
From: burnettk <burnettk@users.noreply.github.com>
Date: Tue, 18 Jun 2024 13:06:41 -0400
Subject: [PATCH] how to build a connector

---
 docs/dev/connector_proxy.md          | 28 ++++++++++++++++++++++++++++
 docs/dev/how_to_build_a_connector.md | 23 +++++++++++++++++++++++
 docs/index.md                        |  1 +
 3 files changed, 52 insertions(+)
 create mode 100644 docs/dev/how_to_build_a_connector.md

diff --git a/docs/dev/connector_proxy.md b/docs/dev/connector_proxy.md
index 3c273ac4..4d33d7c5 100644
--- a/docs/dev/connector_proxy.md
+++ b/docs/dev/connector_proxy.md
@@ -2,3 +2,31 @@
 
 A connector-proxy is an application that is generally deployed alongside frontend and backend.
 Please see [Connector Proxy in 5 mins](https://github.com/sartography/spiff-arena/wiki/Connector-Proxy-in-5-mins).
+
+```mermaid
+graph TD
+    subgraph ConnectorProxy[Connector Proxy Application]
+        direction TB
+        ConnectorA
+        ConnectorB
+    end
+
+    subgraph ConnectorA[Connector A]
+        direction TB
+        CommandA1[Command C]
+        CommandA2[Command D]
+    end
+
+    subgraph ConnectorB[Connector B]
+        direction TB
+        CommandB1[Command E]
+        CommandB2[Command F]
+    end
+
+```
+
+
+Connector Proxies are containers for connectors.
+Connectors are usually python libraries that are included in connector proxy codebases, but they can also be embedded directly inside of connector proxies.
+Our connector-proxy-demo includes a few connectors, including [connector-aws](https://github.com/sartography/connector-aws) and [connector-http](https://github.com/sartography/connector-http).
+Connector http can be used for many API interactions, but you can also [write your own connectors](/dev/how_to_build_a_connector).
diff --git a/docs/dev/how_to_build_a_connector.md b/docs/dev/how_to_build_a_connector.md
new file mode 100644
index 00000000..7400a4c3
--- /dev/null
+++ b/docs/dev/how_to_build_a_connector.md
@@ -0,0 +1,23 @@
+# How to build a connector
+
+While exisiting connectors like connector-http are very flexible, you may choose to build a connector for a specific use case.
+
+To get an idea of what you are in for, take a look at existing connectors:
+* [connector-http](https://github.com/sartography/connector-http/blob/main/src/connector_http/commands/get_request_v2.py)
+* [connector-smtp](https://github.com/sartography/connector-smtp/blob/main/src/connector_smtp/commands/send_email.py)
+
+And there are [many more connectors](https://github.com/sartography?q=connector&type=public&language=python&sort=).
+
+A connector can implement many commands.
+Commands are also known as operators in the SpiffWorkflow frontend properties panel user interface.
+Like the above examples, you will want to inherit from the `ConnectorCommand` class.
+You will see that there are two important functions that your command class must implement:
+
+* `__init__`
+* `run`
+
+Code introspection is used based on the implementation of the `__init__` method to determine which parameters should be allowed in the properties panel.
+The `run` method is where the actual work is done (send http request, etc).
+
+If you end up writing a connector, please consider contributing it back to the community and please consider contributing to this documentation.
+Thank you!
diff --git a/docs/index.md b/docs/index.md
index f0173816..184ede1b 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -14,6 +14,7 @@ dev/setup.md
 dev/backend.md
 dev/frontend.md
 dev/connector_proxy.md
+dev/how_to_build_a_connector.md
 dev/process.md
 ```