Move Adapter documentation from architecture.

Adapters/AdapterChecklists/AdapterDescriptionAndDocumentationGuidelines.md

@@ -0,0 +1,48 @@
+# Adapter Description and Documentation Guidelines
+
+## Table of Contents
+
+- [Must Have](#must-have)
+ - [README.md](#readmemd)
+- [Should Have](#should-have)
+ - [README.md](#readmemd-1)
+ - [component.json](#componentjson)
+- [Could Have](#could-have)
+ - [README.md](#readmemd-2)
+ - [Other Files](#other-files)
+
+
+Adapter repository Requirements:
+
+# Must Have
+## README.md
+- [ ] Description of the application adapter connects to
+- [ ] List of environment variables that need to be configured (e.g. OAuth ClientID/Secret)
+# Should Have
+## README.md
+- [ ] Description of the incoming message and outgoing message for each action/trigger (e.g. Update Contact Action)
+ - [ ] Description of any attachments generated or consumed for each action/trigger
+## component.json
+- [ ] `component.json` should have a global `description` field filled.
+- [ ] `component.json` should have a link to the documentation, e.g. `README` file below
+- [ ] Each field in credentials should have a `note` on it explaining what exactly is required here (unless it's obvious, e.g. password)
+- [ ] Each field except `password` should have a `placeholder` configured with the meaningful sample (unless it's obvious)
+- [ ] Each trigger and action should have a `description` field configured explaining what given trigger/action does
+- [ ] Each field in the trigger/action should have a `note` explaining what expected to be there as well as meaningful example
+ in `placeholder` which could be (for optional fields) a default value if field is empty
+
+# Could Have
+## README.md
+- [ ] Version and compatibility information
+- [ ] Documentation for the authentication process, how to find API key, etc.
+- [ ] Screen shot of the parameters for each action/trigger with sample meaningful values (if parameters are defined for given trigger/action)
+- [ ] Description of the parameters (if any) for each action/trigger
+- [ ] Sample of the minimum viable input (e.g. for updating or creating something) for each action/trigger
+- [ ] Description of the dynamic metadata generation rules, metadata discovery rules for each action/trigger
+- [ ] Known limitations, may be with link to the issue
+- [ ] Contribution guidelines (they should be standardized)
+- [ ] License and copyright
+## Other Files
+- [ ] Logo - 128x128 PNG file with transparent background
+- [ ] License file
+- [ ] Changelog

Adapters/AdapterChecklists/DesiredAdapterBehaviors.md

@@ -0,0 +1,163 @@
+# Desired Adapter Behaviors
+See the section `Given an API how should a adapter behave?` in the document
+`AdapterGuide` to see which questions must be asked and answered to see which
+case your adapter falls into. The following sections list each case and then
+the expected actions and triggers of the adapters.
+
+All items in each list is a **should** have.
+
+## Table of Contents
+
+- [Case 1](#case-1)
+ - [Triggers](#triggers)
+ - [Actions](#actions)
+- [Case 2](#case-2)
+ - [Triggers](#triggers-1)
+ - [Actions](#actions-1)
+- [Case 3](#case-3)
+ - [Triggers](#triggers-2)
+ - [Actions](#actions-2)
+- [Case 4](#case-4)
+ - [Triggers](#triggers-3)
+ - [Actions](#actions-3)
+- [Case 5](#case-5)
+ - [Triggers](#triggers-4)
+ - [Actions](#actions-4)
+- [Case 6](#case-6)
+ - [Triggers](#triggers-5)
+ - [Actions](#actions-5)
+
+## Case 1:
+- The list of business objects is dynamic
+- The structure of the objects is dynamic (*Implied by above statement*)
+- The API supports webhooks
+
+### Triggers
+- [ ] `getObjectsPolling` including functionality to
+ - [ ] supply the list of readable objects
+- [ ] `getObjectsWebhook` including functionality to
+ - [ ] supply the list of readable objects
+ - [ ] supply the structure of the incoming objects
+- [ ] `getDeletedObjectsWebhook` including functionality to
+ - [ ] supply the list of deletable objects
+
+### Actions
+- [ ] `upsertObject` including functionality to
+ - [ ] supply the list of writable objects
+ - [ ] supply the structure of the incoming object
+- [ ] `deleteObject` including functionality to
+ - [ ] supply the list of deletable objects
+- [ ] `lookupObjectByField` including functionality to
+ - [ ] supply the list of readable objects
+ - [ ] supply the list of fields that can be searched
+
+## Case 2:
+- The list of business objects is dynamic
+- The structure of the objects is dynamic (*Implied by above statement*)
+- The API does not support webhooks
+
+### Triggers
+- [ ] `getObjectsPolling` including functionality to
+ - [ ] supply the list of readable objects
+- [ ] `getDeletedObjectsPolling` (if possible)
+ - [ ] including functionality to supply the list of deletable objects
+
+### Actions
+- [ ] `upsertObject` including functionality to
+ - [ ] supply the list of writable objects
+ - [ ] supply the structure of the incoming object
+- [ ] `deleteObject` including functionality to
+ - [ ] supply the list of deletable objects
+- [ ] `lookupObjectByField` including functionality to
+ - [ ] supply the list of readable objects
+ - [ ] supply the list of fields that can be searched
+
+## Case 3:
+- The list of business objects is static
+- The structure of the objects is dynamic
+- The API supports webhooks
+
+### Triggers
+- [ ] `getObjectsPolling` including
+ - [ ] the static list of readable objects
+- [ ] `getObjectsWebhook` including
+ - [ ] the static list of readable objects
+ - [ ] functionality to supply the structure of the incoming objects
+- [ ] `getDeletedObjectsWebhook` including
+ - [ ] the static list of deletable objects
+
+### Actions
+- [ ] `upsertObject` including
+ - [ ] the static list of writable objects
+ - [ ] functionality to supply the structure of the incoming object
+- [ ] `deleteObject` including
+ - [ ] the static list of deletable objects
+- [ ] `lookupObjectByField` including functionality to
+ - [ ] the static list of readable objects
+ - [ ] supply the list of fields that can be searched
+
+## Case 4:
+- The list of business objects is static
+- The structure of the objects is dynamic
+- The API does not support webhooks
+
+### Triggers
+- [ ] `getObjectsPolling` including
+ - [ ] the static list of readable objects
+- [ ] `getDeletedObjectsPolling` (if possible)
+ - [ ] including the static list of readable objects
+
+### Actions
+- [ ] `upsertObject` including
+ - [ ] the static list of writable objects
+ - [ ] functionality to supply the structure of the incoming object
+- [ ] `deleteObject` including
+ - [ ] the static list of deletable objects
+- [ ] `lookupObjectByField` including functionality to
+ - [ ] the static list of readable objects
+ - [ ] supply the list of fields that can be searched
+
+## Case 5:
+- The list of business objects is static
+- The structure of the objects is static
+- The API supports webhooks
+
+### Triggers
+- [ ] `getObjectsPolling` including
+ - [ ] the static list of readable objects
+- [ ] `getObjectsWebhook` including
+ - [ ] the static list of readable objects
+ - [ ] the static structure of the incoming objects
+- [ ] `getDeletedObjectsWebhook` including
+ - [ ] the static list of deletable objects
+
+### Actions
+- [ ] `upsertObject` including
+ - [ ] the static list of writable objects
+ - [ ] the static structure of the incoming object
+- [ ] `deleteObject` including
+ - [ ] the static list of deletable objects
+- [ ] `lookupObjectByField` including functionality to
+ - [ ] the static list of readable objects
+ - [ ] the static list of fields that can be searched
+
+## Case 6:
+- The list of business objects is static
+- The structure of the objects is static
+- The API does not support webhooks
+
+### Triggers
+- [ ] `getObjectsPolling` including
+ - [ ] the static list of readable objects
+- [ ] `getDeletedObjectsPolling` (if possible)
+ - [ ] including the static list of readable objects
+
+### Actions
+- [ ] `upsertObject` including
+ - [ ] the static list of writable objects
+ - [ ] the static structure of the incoming object
+- [ ] `deleteObject` including
+ - [ ] the static list of deletable objects
+- [ ] `lookupObjectByField` including functionality to
+ - [ ] the static list of readable objects
+ - [ ] the static list of fields that can be searched

Adapters/AdapterChecklists/README.md

@@ -0,0 +1,10 @@
+# Completeness Checklists for Adapters
+
+The documents in this folder are designed to be checklists. Here is a list of
+current checklists:
+* `AdapterDescriptionAndDocumentationGuidelines.md`: Describes what should be
+ documented in the adapter `README.md`,`component.json` and similar files.
+* `DesiredAdapterBehaviors.md`: Lists what behaviors should be present in a
+ complete adaptor.
+* `RequirementsToTestOrBuildAnAdapter.md`: List what is access to a system is
+ required to build or test an adapter.

Adapters/AdapterChecklists/RequirementsToTestOrBuildAnAdapter.md

@@ -0,0 +1,17 @@
+# Requirements to Test or Build an Adapter
+In order for an individual to test the correctness of an adapter or to build an
+adapter for a new system, the following resources are must haves in order to
+access the API:
+- [ ] An instance/account/tenant for the tester to use. This includes:
+ - [ ] A server where the API is set up (or the API is already hosted in the cloud)
+ - [ ] All services/daemons to process the API and webhooks are running
+ - [ ] The necessary software licenses are provided so that the software may be
+ run in the configuration
+- [ ] The tester must have permission to:
+ - [ ] Log in to the test account/system
+ - [ ] Create, Update and Delete objects as required in the UI of the system
+ - [ ] Configure API access for the adapter
+- [ ] Data in the test instance/account/tenant can only be manipulated by the
+tester and the adapter. (No shared test instances/accounts/tenants.)
+- [ ] The tester must be provided all API keys that are required in order for
+the adapter to interact with the API