External sync units extraction

An external sync unit refers to a single unit in the external system that is being airdropped 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.

In the external sync unit extraction phase, the snap-in is expected to obtain a list of external sync units that it can extract from the external system API and send it to Airdrop in its response.

External sync unit extraction is executed only during the initial import.

Implementation

This phase should be implemented in the external-sync-units-extraction.ts file.

The snap-in should emit the list of external sync units in the given format:

1const externalSyncUnits: ExternalSyncUnit[] = [
2  {
3    id: "devrev",
4    name: "devrev",
5    description: "Demo external sync unit",
6    item_count: 100,
7  },
8];
  • 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 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.

The snap-in must respond to Airdrop with a message, which contains a list of external sync units as a payload:

1await adapter.emit(ExtractorEventType.ExtractionExternalSyncUnitsDone, {
2  external_sync_units: externalSyncUnits,
3});

or an error:

1await adapter.emit(ExtractorEventType.ExtractionExternalSyncUnitsError, {
2  error: {
3    message: "Failed to extract external sync units. Lambda timeout.",
4  },
5});

To test your changes, start a new airdrop in the DevRev App. If external sync units extraction is successful, you should be prompted to choose an external sync unit from the list.

Built with