Data Import Component

---

1. Component Overview

Purpose:

• To serve as an intermediary step after data sync so the user can decide how to handle each new, unlinked object.
• To display all unlinked objects (those with no parent ID) and provide options for linking or creating new records.

User Goals:

• Identify which objects need attention.
• Choose to connect an object to an existing record (link) or treat it as a new object (add).

---

2. UI Design & Layout

Header & Instructions

• Title: “Review Imported Objects”
• Subtext: A brief explanation, e.g.,
  “Below are the objects imported from your latest sync that are not yet linked to a local record. For each object, you can either link it to an existing entry or create a new record.”

Main Content – Unlinked Objects List

• Display Format:
  Use a table (or card layout) to present the unlinked objects. For each row (or card), include:

  • Key Identifiers: Name, external ID, or any descriptor provided by the sync.
  • Import Timestamp: When the object was added (optional but useful for context).
  • Source: Indicate the integration platform if applicable.

• Actions Per Object:

  • Link to Existing:
    A button (or icon) that, when clicked, opens a modal dialog for selecting an existing local object.
  • Add New Local:
    A button that opens a form (inline or modal) with pre-populated details from the imported data and allows the user to complete any additional fields necessary for the new record.

• Additional Features:

  • Search/Filter:
    A search box or filters to help users quickly locate a particular object if the list is long.
  • Bulk Actions (Optional):
    Checkboxes might allow the user to perform linking or adding actions on several objects simultaneously if needed.

Modal Dialog for Linking

• Contents:
  • Searchable List of Existing Local Objects:
    Display the list of candidate local objects (which could be listings, properties, or another entity type depending on your domain). Include search, filter, or pagination if necessary.
  • Selection Mechanism:
    Allow the user to choose one and confirm the linking action.
  • Feedback:
    Once a link is confirmed, update the state of the unlinked object in the UI (possibly remove it from the list).

New Object Creation Flow

• Form Modal/Page:
  Present a form pre-populated with data from the unlinked sync object.
• Editable Fields:
  Allow the user to adjust details (e.g., name, description, additional metadata) before saving.
• On Save:
  Persist the new record and update the linkage in the database so that the imported object is now connected.

---

3. Interaction Flow & Navigation

Step 1: Sync Completion & Navigation

• In your current integration sync handler:
  After the sync API call completes successfully, navigate to the new import review route.

  // Example (Angular):
  this.integrationSyncService.syncIntegrationAsync(connection.integrationProvider.integrationId)
    .pipe(finalize(() => this.isIntegrationSyncing = false))
    .subscribe({
      next: () => {
        this.snackBar.open('Sync started successfully!', 'Close', { duration: 3000 });
        // Navigate to the ImportReviewComponent when sync completes:
        this.router.navigate(['/import-review']);
      },
      error: (error) => {
        console.error('Sync failed', error);
        this.snackBar.open('Sync failed. Please try again.', 'Close', { duration: 3000 });
      }
    });

Step 2: ImportReviewComponent Initialization

• Fetching Data:
  On initialization, call a service method (e.g., ImportedDataService.getUnlinkedObjects()) to load all unlinked objects.
• Loading State:
  Use a spinner or loading indicator while fetching data.

Step 3: User Action – Linking an Object

• User clicks “Link to Existing”:
  • Open the linking modal.
  • In the modal, allow the user to search or browse existing local objects.
  • On selection and confirmation, call a service endpoint (e.g., ImportedDataService.linkObject(importId, localObjectId)) to update the object’s linkage.
  • Refresh the list or remove the object from the unlinked list upon success.

Step 4: User Action – Adding a New Object

• User clicks “Add New Local”:
  • Open the new object creation form (possibly in a modal).
  • Pre-fill form fields with data from the imported object.
  • On form submission, call a service endpoint (e.g., LocalObjectService.createFromImportedData(importData)) to create a new local record and update the linkage.
  • Update the UI to reflect the new link.

---

4. Technical Considerations

API & Service Layer

• Fetching Unlinked Data:
  • Create an endpoint (e.g., GET /api/imported/unlinked) that returns objects with a null parent ID.
• Linking Operation:
  • Define an endpoint (e.g., POST /api/imported/{id}/link) which receives the selected local object’s ID and updates the imported record.
• New Object Creation:
  • The new record creation endpoint should accept the imported data payload and create an object accordingly while marking it as linked.

Error Handling & Notifications

• Error Feedback:
  Use snackbars or modal alerts to indicate errors in linking or adding new records.
• Success Feedback:
  Notify the user upon successful linkage or creation.

Testing Strategy

• Unit Tests:
  Write tests for the component’s logic, including fetching, modal interactions, and service call responses.
• Integration Tests:
  Verify end-to-end flows, ensuring that linking or adding a new object correctly updates both the UI and the backend (refer to your Testing Strategies document for setting up your test environments citeturn0file0).

Role Considerations

• Access Control:
  Though the UI should be accessible by default, check whether linking and creating new records need any role validation. Ensure that the actions available are consistent with the RBAC model described in your Role‐Based-Access-Control documentation citeturn0file1.

---

5. Summary Diagram

1. Sync Flow:

   • User clicks sync
   • API call to sync objects
   • On success, navigate to ImportReviewComponent

2. ImportReviewComponent:

   • Header: “Review Imported Objects”
   • List: Display all unlinked objects in table/card layout
   • Row Actions: “Link to Existing” ➔ Opens modal, “Add New” ➔ Opens pre-filled form
   • Service Calls:
     • Fetch unlinked data
     • Update linking status
     • Create new object from imported data

3. Modal & Form Interactions:

   • Link Modal: Select existing object and confirm
   • Add Form: Edit and submit new local object details

---