Import Data User Guide

Overview

The Topics Import feature allows you to bulk import Fact Cards (topics) into your workspace using Excel spreadsheets. This is particularly useful for migrating data from other systems or performing bulk updates to existing Fact Cards.

Step 1: Download a Template

1. Navigate to the Settings → Import Topics page
2. Select the Fact Card type you want to import from the tab menu.
3. Click New Template to get an Excel file with the correct structure for importing new data.
4. Click Update template to get an Excel file with the correct struture for importing updated data.

Step 2: Prepare Your Data

Header Information

• Row 1: Database field references (hidden from users)
• Row 2: Section titles and descriptions
• Row 3: Column headers with human-readable names

Required Columns

• ID: UUID of existing Fact Card (for updates)
• Name: Fact Card name (required for new Fact Cards)
• Aliases: Alternative names
• Description: Detailed description
• Import Handler: Controls how the row is processed

Import Handler Options

Step 3: Add Your Data

Creating New Fact Cards

1. Leave the ID column empty
2. Fill in the Name column (required)
3. Add any additional data (aliases, description, etc.)
4. Set Import Handler to "Create/update"

Updating Existing Fact Cards

1. Copy the UUID from the existing Fact Card to the ID column
2. Update the fields you want to change
3. Set Import Handler to "Create/update"

Archiving Fact Cards

1. Copy the UUID from the existing Fact Card to the ID column
2. Set Import Handler to "Archive"

Step 4: Add Related Data

Groups and Categories

• Use the Group columns to assign Fact Cards to organizational groups
• For hierarchical groups, use Group.1, Group.2, etc.

Facts (templtaes)

• Add assessment data using Assessment, Link, Detail or Partnership columns
• Values should match the scale values defined in your workspace

Tags

• Use Tag Group columns to assign tags
• Multiple tags can be separated by semicolons

Relationships

• Parent: Reference another Fact Card as a parent

Step 5: Upload and Import

1. Save your Excel file
2. Return to the Import Topics page
3. Select the Fact Card type that matches your data
4. Click Choose File and select your Excel file
5. Click Submit file

Import Process

Validation

1. File Format: Ensures the file is a valid Excel spreadsheet
2. Fact Card Type: Detects the type of Fact Cards being imported
3. Column Headers: Validates that required columns are present
4. Data Validation: Checks for required fields and valid values
5. Import Handler Rules: Ensures proper import handler configuration

Processing

1. Topic Lookup: Finds existing Fact Card by ID or name
2. Data Processing: Applies updates based on import handler
3. Related Data: Processes groups, assessments, tags, and relationships
4. Archive/Destroy: Performs archive or delete operations if specified

Error Handling

Common Errors

"Couldn't infer Fact Card type"

• Cause: Missing or invalid Fact Card type information
• Solution: Re-download the template and ensure the first row contains the correct Fact Card type

"No Fact Cards detected"

• Cause: No data rows found in the spreadsheet
• Solution: Add data rows starting from row 4

"A Fact Card requires a name unless an ID is provided"

• Cause: Row missing both name and ID
• Solution: Provide either a name (for new Fact Cards) or ID (for existing Fact Cards)

"Couldn't find Fact Card with ID [uuid]"

• Cause: Referenced Fact Card doesn't exist in the workspace
• Solution: Verify the UUID is correct or create the Fact Card first

Error Display

Errors are displayed in a table showing:

• Row Number: Where the error occurred
• Error Message: Description of the problem
• Suggested Action: How to fix the issue

Best Practices

Data Preparation

1. Use Templates: Always start with a downloaded template
2. Validate Data: Check for typos and missing required fields
3. Test Small: Import a few rows first to verify the process
4. Backup: Export existing data before bulk updates

Import Strategy

1. Create First: Import new Fact Cards before creating relationships
2. Update Carefully: Use specific IDs when updating existing Fact Cards. Only update those cards you wish to change.
3. Archive/Purge Safely: Verify Fact Cards before archiving
4. Monitor Results: Check the import summary after completion

Performance Considerations

• File Size: Keep files under 10MB for best performance
• Row Count: Process large datasets in batches of 1000 rows
• Network: Use a stable internet connection for large imports

Advanced Features

Multi-Groupable Fact Cards

Apps and Technologies can belong to multiple groups:

• Use All data handler to update all information
• Use Add group only to add to additional groups
• Use Remove group only to remove from specific groups

Hierarchical Groups

Support for nested group structures:

• AppGroup L0: Top-level group
• AppGroup L1: Second-level group
• AppGroup L2: Third-level group
• And so on...

Assessment Data

Import assessment responses:

• Scale Values: Use exact names from your assessment scales
• Numeric Values: For numeric assessments, use decimal values
• Date Values: Use ISO format (YYYY-MM-DD)

Tag Management

Bulk tag assignment:

• Multiple Tags: Separate with semicolons
• New Tags: Automatically created if they don't exist
• Tag Groups: Organize tags by groups

Troubleshooting

Check the History tab and click on your import to review detailed information.

Import Fails Completely

1. Check file format (must be .xlsx)
2. Verify Fact Card type in first row
3. Ensure at least one data row exists
4. Check for corrupted Excel file

Partial Import Success

1. Review error messages for specific rows
2. Fix data issues in the problematic rows
3. Re-import only the corrected rows
4. Use the "Skip" handler for problematic rows

Performance Issues

1. Reduce file size by removing unused columns
2. Process data in smaller batches
3. Check network connection stability

Support

1. Check Error Messages: Review the detailed error descriptions
2. Export Template: Compare your data with a fresh template
3. Contact Support: Provide the error messages and file details