Migrate entities definitions to separate pages.

Author: samod

fern/docs/pages/adaas/extracting-attachments.mdx

@@ -3,10 +3,14 @@
 For the Attachment Extraction phase of the import process,
 the Extractor has to upload each attachment to DevRev’s S3 using the `S3Interact` API. 
 
-After uploading an attachment or a batch of attachments, the Extractor also has to prepare and upload an SSOR attachment file.
-It should contain the DevRev IDs of the extracted attachments, along with the parent and actor IDs from the External System.
-This needs to be done because only the Extractor knows to what the attachment was attached in the External system.
-The SSOR attachment file should then be sent just like any normal Artifact, but with the `ssor_attachment` item type.
+After uploading an attachment or a batch of attachments, the extractor also has to prepare and upload a file specifying
+the extracted and uploaded attachments.
+
+It should contain the DevRev IDs of the extracted and uploaded attachments, along with the parent domain object ID
+from the external system and the actor ID from the external system.
+
+The uploaded artifact is structured like a normal artifact containing extracted data in JSON Lines format with specifying the
+`ssor_attachment` as an item type.
 
 ## Examples
 

fern/docs/pages/adaas/extracting-external-sync-units.mdx

@@ -4,14 +4,25 @@ In the External Sync Unit extraction phase, the Extractor is expected to get the
 (whatever the equivalent of those is called in the External System)
 that it can extract with the provided credentials and send it to Airdrop in its response.
 
+An External Sync Unit refers to a single unit in the [External System](#external-system) that we are airdropping to DevRev.
+In some systems, this is a project, in some it is a repository, in support systems this External Sync Unit could be called a brand or an organization.
+What a unit of data is called, and what it represents depends on the [External System](#external-system)'s domain model.
+It usually combines contacts, users, work-like items, and comments into a unit of domain objects.
+
+Some [External Systems](#external-system) may offer a single unit in their free plans,
+while their enterprise plans may offer their clients to operate many separate units.
+
+The External Sync Unit ID is the identifier of the project, repository, etc. in the [External System](#external-system).
+For GitHub, this would be the repository, for example `cli` in `github.com/devrev/cli`.
+
 The most important structure in the message is the list of External Sync Units (event_data.external_sync_units in JSON),
 which contains the following fields:
 - ID: This is the unique identifier in the External System
 - Name: This is the human-readable name in the External System
 - Description: A short description if the External System provides it
 - Item count (item_count): The number of items (issues, tickets, comments, etc.) in the External System,
 if it can be obtained in a very lightweight manner, such as by calling a special API endpoint.
-If there is no such way to get it, i.e., the items would need to be extracted to count them,
+If there is no such way to get it, for example, the items would need to be extracted to count them,
 then the item count should be `-1`, to avoid blocking the import with long-running queries.
 
 Example:

fern/docs/pages/adaas/extracting-metadata.mdx

@@ -5,8 +5,7 @@ and upload it as an Artifact with item type `initial_domain_mapping`.
 
 The file provides mappings between External System domain entities and DevRev domain entities.
 
-For each extracted domain entity from the External System,
-the Extractor must provide at least one mapping to a DevRev domain entity.
+For each extracted domain entity from the External System, the Extractor must provide at least one mapping to a DevRev domain entity.
 
 If two or more possible mappings are provided within `possible_targets`, end-users will be able to select
 to what DevRev domain entity they would like to have it transformed during the mapping phase of the extraction.

fern/docs/pages/adaas/extraction-phases.mdx

@@ -1,10 +1,7 @@
 # Extraction phases
 
-Airdrop extractions are done in phases.
-Phases follow sequentially, and each can consist of one or more invocations of the Worker.
-
-A Worker has the responsibility of maintaining its own state that persists between phases in a Sync Run,
-as well as between Sync Runs.
+Airdrop extractions are done in sync runs, and each sync run is comprised out of phases.
+Phases follow sequentially, and each can consist of one or more invocations of the worker.
 
 ```mermaid
 ---
@@ -76,10 +73,12 @@ A 1-way Sync consists of the following phases:
 A 1-way Sync extracts only the domain objects updated and/or created since the previous successful Sync Run.
 
 A Deletion Sync consists of the following phases:
-- Delete data,
-- Delete attachments.
+- Data deletion,
+- Attachments deletion.
+
+## Event types per extraction phases
 
-## External sync unit extraction
+### External sync unit extraction
 
 External Sync Unit Extraction is an extraction phase, executed only during the Initial Import.
 It extracts External Sync Units available in the External System,
@@ -91,7 +90,7 @@ Airdrop initiates the External Sync Unit Extraction phase by starting the Worker
 The Worker must respond to Airdrop with a message with eventType `EXTRACTION_EXTERNAL_SYNC_UNITS_DONE`
 with a list of External Sync Units as a payload, or `EXTRACTION_EXTERNAL_SYNC_UNITS_ERROR` in case of an error.
 
-## Metadata extraction
+### Metadata extraction
 
 Airdrop initiates the Metadata Extraction by starting the Worker with a message with eventType: `EXTRACTION_METADATA_START`.
 
@@ -102,7 +101,7 @@ to prepare and upload the Initial Domain Mapping to DevRev.
 The Worker must respond to Airdrop with a message with eventType `EXTRACTION_METADATA_DONE` when done,
 or `EXTRACTION_METADATA_ERROR` in case of an error.
 
-## Data extraction
+### Data extraction
 
 Airdrop initiates Data Extraction by starting the Worker with a message with eventType `EXTRACTION_DATA_START`
 when transitioning to the Data Extraction phase.
@@ -124,7 +123,7 @@ Once the Data Extraction is done, the Worker must respond to Airdrop with a mess
 
 If Data Extraction failed in any moment of extraction, the Worker must respond to Airdrop with a message with eventType `EXTRACTION_DATA_ERROR`.
 
-## Attachments extraction
+### Attachments extraction
 
 Airdrop initiates the Attachment Extraction by starting the Worker with a message with eventType `EXTRACTION_ATTACHMENTS_START`
 when transitioning to the Data Extraction phase.
@@ -146,7 +145,7 @@ Once the Attachment Extraction phase is done, the Worker must respond to Airdrop
 
 If Attachment Extraction failed, the Worker must respond to Airdrop with a message with eventType `EXTRACTION_ATTACHMENTS_ERROR`.
 
-## Delete data
+### Data deletion
 
 Airdrop initiates the Data Delete phase when the Sync is deleted from DevRev.
 It is started by sending the Worker a message with eventType: `EXTRACTION_DATA_DELETE`.
@@ -156,7 +155,7 @@ In the most common extraction use cases, there is nothing to do and Workers may
 
 The Worker must respond to Airdrop with a message with eventType `EXTRACTION_DATA_DELETE_DONE` when done or `EXTRACTION_DATA_DELETE_ERROR` in case of an error.
 
-## Delete attachments
+### Attachments deletion
 
 Airdrop initiates the Attachments Delete phase when the Sync is deleted from DevRev.
 It is started by sending the Worker a message with eventType: `EXTRACTION_ATTACHMENTS_DELETE`.

fern/docs/pages/adaas/getting-started.mdx

@@ -21,14 +21,17 @@ See [Creating a Keyring](https://www.notion.so/Creating-a-Keyring-aa497671dc1b42
 
 ## Creating keyrings
 
-Keyrings are a DevRev-specific mechanism for managing authentication for External Systems.
-They are called Connections in the DevRev app.
+Keyrings are a DevRev-specific mechanism for managing authentication to external systems.
+They are called **Connections** in the DevRev app.
 
-They provide a secure way to store and manage credentials within your DevRev Snap-In.
+Keyrings provide a secure way to store and manage credentials within your DevRev Snap-In.
 This eliminates the need to expose sensitive information like passwords
 or access tokens directly within your code or configuration files, enhancing overall security.
 
-Read more about Keyrings in the [developer documentation](https://developer.devrev.ai/snapin-development/references/keyrings).
+A keyring is used by a worker to authenticate to the external system in API calls. They includes the key (for example,
+a PAT token or API key), its type, the organization ID for which a key is valid, and in some cases the organization name.
+
+Read more about keyrings in the [developer documentation](/snapin-development/references/keyrings).
 
 
 ## Observability
@@ -38,4 +41,4 @@ Workers are snap-ins, and they inherit observability methodology from snap-ins.
 To observe logs from your Worker in your development environment use `devrev snap_in_package logs | jq`.
 To open logs in your favorite editor use `devrev snap_in_package logs | code -`
 
-See also: https://developer.devrev.ai/snapin-development/debugging
+See also [debugging snap-in](/snapin-development/debugging).

fern/docs/pages/adaas/overview.mdx

@@ -1,42 +1,49 @@
 # Airdrop-as-a-Service (ADaaS)
 
-Airdrop-as-a-Service (ADaaS) as a system consists of the internal Airdrop components and a Worker (Extractor or Loader),
-which is a Snap-In with a predefined structure.
-These Workers (Extractors and Loaders) can be built by anyone, not just DevRevelers.
-
-This section explains how ADaaS works at a high level.
-Message protocols and other specifics can be found in the Extractor and Loader sections.
-
-Airdrop uses its own AWS S3 structure
-(and its own buckets) and that only Airdrop components have access to it.
-This means that Workers can’t access these buckets directly,
-which is why all their data has to be uploaded to DevRev through S3Interact.
-
-For clarity, Artifact API and Airdrop are shown as separate entities,
-even though they are both accessed through DevRev’s API.
-Worker is shown as external, to clarify that it is developed by third parties,
-even though it runs on DevRev’s infrastructure.
-
-```mermaid
----
-title: ADaaS architecture high-level overview
----
-graph TB
-externalSystem[External system]
-worker([Worker])
-s3interact[s3interact]
-airdrop[Airdrop]
-s3[(AWS S3)]
-
-	externalSystem <-- Get/create users, issues, ... --> worker
-	
-	worker <-- Exchange artifact upload/download URLs --> s3interact
-	worker <-- Upload/download artifacts --> s3
-	worker <-- ADaaS messages and REST API --> airdrop
-
-	
-	subgraph DevRev
-	s3interact <-- Prepare upload/download URL --> s3
-	airdrop <-- Download/upload artifacts --> s3
-	end
-```
+Airdrop is DevRev’s solution to migrate data. It allows our customers to bring in their existing data from
+external systems and, data back to external systems, and keep data in sync between DevRev and the external systems.
+You can read more about Airdrop in the [general documentation](https://docs.devrev.ai/import#airdrop-features).
+
+Airdrop-as-a-Service (ADaaS) gives snap-in developers the ability to integrate with DevRev’s Airdrop functionality.
+It enables developers to create external workers, extractors and loaders to bring data from various external systems.
+
+![ADaaS architecture](../../img/adaas/adaas-architecture.svg)
+
+An extractor is an function in an ADaaS-capable snap-in responsible for extracting data from an external system, such as Jira, Zendesk,
+HubSpot, etc. It uses a standardized communication protocol for talking to Airdrop and a standardized
+data structure for all the files it extracts and processes, so that they can be seamlessly imported into DevRev.
+
+## Sync runs
+
+Airdrop functions are executed in the context of sync runs, which is a directed operation that spans over many invocations
+of ADaaS snap-in to bring the data to DevRev or load the data to the external system.
+
+A forward sync run is a sync from an external system to DevRev. An extractor is used to extract the created and/or
+updated data from the external system, such as Jira, Zendesk, HubSpot, etc. to DevRev. An extractor function
+in the snap-in is responsible for extracting data from the external system. It uses standardized communication protocol
+for talking to [Airdrop](https://docs.devrev.ai/import#airdrop-features) and a standardized data structure for all the files
+it extracts and processes, so that they can be transformed, deduplicated and seamlessly imported into DevRev.
+
+A reverse sync run is a sync from DevRev to an external system. It uses a loader function, to create and/or update data
+in the external system.
+
+## Sync modes
+
+### Initial import
+
+An initial import is the first import of data from the external system to DevRev.
+It is triggered manually by the end user in DevRev's Imports UI.
+
+## 1-way sync
+
+A 1-way sync refers to any extraction after the initial import has been successfully completed.
+An extractor extracts data that was created and/or updated in the external system
+after the start of the latest successful forward sync, including any changes that occurred during the
+forward sync, but were not picked up by it.
+
+A snap-in must consult its state to get information on when the last successful forward sync started. ADaaS snap-ins
+must maintain its own state that persists between phases in a sync run, as well as between sync runs.
+
+
+
+