Team import

AirSync supports two ways to work with teams: a sync unit level team and team record type mapping. The two approaches can be used on their own or combined.

Sync unit level team

A sync unit level team acts as a top-level container for an entire sync unit.

• Behavior: When defined, AirSync automatically creates a team in DevRev that represents the whole external sync unit.
• Scope: Issues, enhancements, and sprints imported through the sync unit are scoped to the sync unit level team. Subtypes (customizations) of issues and enhancements are also scoped to this team. This provides a consistent hierarchy for all imported data without needing complex mappings or any extra configuration from the end user.

To trigger the creation of a sync unit level team, extend your external domain metadata (EDM) with the team_data field.

EDM schema definition:

{
  "team_data": {
    "key": "string, required",
    "name": "string, required"
  }
}

Developer requirements:

• Consistency: The key and name must be stable across all sync runs.
• Key format: The key must adhere to the platform-wide team key regex: ^[A-Z]{3,5}$ (3 to 5 uppercase letters).
• Immutability: Once a key is set, it must not be changed. Ensure your mapping logic generates permanent, unique keys.

Adding members to the sync unit level team

To assign users to the sync unit level team, declare a record type in your EDM that maps to the object_member object, the same way you would for group memberships.

To target the sync unit level team specifically (instead of a regular group), use the special identifier string __airsync_sync_level_team as the value of the object_id field in your extracted data. AirSync recognizes this value and automatically resolves it to the sync unit level team's members.

Example extracted data for a membership record that adds two users to the sync unit level team:

{
  "object_id": "__airsync_sync_level_team",
  "add_member_ids": ["ext_user-1", "ext_user-2"]
}

Team record type mapping

Team record type mapping lets you map your external system's own team entities as a standard record type in your connector.

• Behavior: Mapped teams are treated as first-class objects. You can map your external team entities directly to DevRev team objects, the same way you would map any other record type.
• Scope: Synced issues, enhancements, and sprints can be scoped to the imported teams by referencing them inside the team_id field.
• Interaction: If a sync unit level team is defined, all mapped teams are automatically treated as children of it. If no sync unit level team is defined, mapped teams are created at the global organization level (no parent).

If your external system has its own concept of teams that resembles DevRev teams, map them as a standard record type in your connector.

Schema requirements:

• Required fields: key, name, description.
• Parent field: Include a parent field to define hierarchy.

Logic:

• If you map a parent field, that relationship is honored.
• If you leave the parent field null or empty, AirSync automatically falls back to the sync unit level team (if one exists). This ensures your mapped teams don't become "orphaned" at the global level if you intended them to belong to the sync unit.

Adding members to mapped teams

To assign users to a team created through team record type mapping, declare a record type in your EDM that maps to the object_member object, the same way you would for group memberships.

Set the object_id field to the external identifier of the mapped team record you want to target, and populate the membership itself using either the add_member_ids or member_id field.

Example extracted data for a membership record that adds two users to a mapped team:

{
  "object_id": "ext_team-1",
  "add_member_ids": ["ext_user-1", "ext_user-2"]
}

Limitations and best practices

Scenarios

Basic sync (sync unit level team only)

• Goal: Group everything under one container.
• Implementation: Define team_data in EDM.
• Result: All imported issues, enhancements, sprints, and subtypes are scoped to this team. No team records are imported through team record type mapping.

Hierarchical sync (sync unit level team + team record type mapping)

• Goal: Sync a hierarchy (for example, Engineering -> Specific Project Teams).
• Implementation:
  • Define team_data in EDM (the Engineering).
  • Map a team record type (the Project Teams).
• Result: The "Engineering" team acts as the parent, and the "Project Teams" are created as its children. Issues, enhancements, and sprints with team_id populated are scoped to their respective "Project Team", and by extension fall under the "Engineering" hierarchy. Any of these records left with team_id empty fall back to the "Engineering" team directly. Subtypes are always scoped to the "Engineering" team.

Team record type mapping only (no sync unit level team)

• Goal: Import your external system's teams as-is, without an umbrella container.
• Implementation: Do not define team_data in EDM. Map a team record type.
• Result: Mapped teams are created at the Global/Org level, honoring whatever parent field you map between them, but with no fallback parent since there is no sync unit level team. Issues, enhancements, and sprints with team_id populated are scoped to their mapped team. Any of these records left with team_id empty, and all subtypes, are scoped to the Global/Org level instead, since there's no sync unit level team to fall back to.