External sync units extraction

In the external sync unit extraction phase, the extractor is expected to obtain a list of external sync units 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 that we are airdropping to DevRev. In some systems, this is a project; in some it is a repository; in support systems it could be called a brand or an organization. What a unit of data is called and what it represents depends on the external system’s domain model. It usually combines contacts, users, work-like items, and comments into a unit of domain objects.

Some external systems 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 sync unit (project, repository or similar) in the external system. For GitHub, this would be the repository, for example cli in github.com/devrev/cli.

Triggering event

External sync unit extraction is executed only during the initial import. It extracts external sync units available in the external system, so that the end user can choose which external sync unit should be airdropped during the creation of an Import in the DevRev App.

Airdrop initiates the external sync unit extraction phase by starting the worker with a message with an event of type EXTRACTION_EXTERNAL_SYNC_UNITS_START.

The snap-in must respond to Airdrop with a message with an event of type EXTRACTION_EXTERNAL_SYNC_UNITS_DONE, which contains a list of external sync units as a payload, or EXTRACTION_EXTERNAL_SYNC_UNITS_ERROR in case of an error.

Snap-in response

The snap-in provides the list of external sync units in the provided event message event_data.external_sync_units containing the following fields:

• id: The unique identifier in the external system.
• name: The human-readable name in the external system.
• description: The short description if the external system provides it.
• item_count: The number of items (issues, tickets, comments or others) in the external system. Item count should be provided if it can be obtained in a very lightweight manner, such as by calling an API endpoint. If there is no such way to get it (for example, if 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:

1
[
2
  {
3
    "id": "a-microservice-repository",
4
    "name": "A Microservice Repository",
5
    "description": "Our greatest microservice repo",
6
    "item_count": 232
7
  }
8
]