Anchoring Scenarios & Troubleshooting¶

This page covers recommended practices, common real-world anchoring scenarios, and resolutions for issues you may encounter while anchoring an ASBO. For the core concepts and step-by-step procedures, see Anchoring Concept & Table Selection Wizard and The Table Mapper.

Best Practices for Anchoring¶

Pre-Anchoring Planning¶

Before beginning the anchoring process:

Understand Your Data Model¶

• ✓ Review the database table structure thoroughly
• ✓ Understand the meaning and purpose of each column
• ✓ Identify primary keys and required columns
• ✓ Document any business rules or constraints

Plan Your ASBO Structure¶

• ✓ Decide which columns should map to which attributes
• ✓ Determine appropriate logical data types
• ✓ Identify which attributes will serve as RN and RD
• ✓ Consider future scalability and additional environments

Verify Prerequisites¶

• ✓ Ensure datasource connectivity is stable
• ✓ Confirm you have appropriate database permissions
• ✓ Test datasource connection before anchoring
• ✓ Verify the target table contains actual data (if possible)

During Anchoring¶

Systematic Mapping Approach¶

• ✓ Map critical attributes first (primary key, RN, RD candidates)
• ✓ Review each type incompatibility warning carefully
• ✓ Use meaningful attribute names if creating new attributes
• ✓ Document any type mutations or transformations applied

Validation and Review¶

• ✓ Double-check all mappings before saving
• ✓ Verify that required business attributes are mapped
• ✓ Ensure data types make logical sense for the use case
• ✓ Test drag-and-drop operations before committing

Post-Anchoring Actions¶

Immediate Follow-up¶

• ✓ Configure RN and RD for the anchored ASBO
• ✓ Perform a test import of a small number of resources
• ✓ Verify imported data matches expectations
• ✓ Review and validate the master environment mapping

Documentation¶

• ✓ Document the anchoring decision and rationale
• ✓ Record which datasource/schema/table was selected
• ✓ Note any special mappings or type mutations
• ✓ Update team documentation and knowledge base

Testing and Validation¶

• ✓ Import a sample set of resources
• ✓ Verify all mapped attributes are populated correctly
• ✓ Test RN and RD rendering
• ✓ Validate data integrity and completeness

Common Anchoring Scenarios¶

Scenario 1: Anchoring a New ASBO to an Existing Table¶

Situation: You manually created an ASBO and need to link it to an existing database table.

Steps:

1. Click the "Anchor" button on the newly created ASBO
2. Select the appropriate datasource, schema, and table
3. Review the table structure using the schema viewer
4. Open the Table Mapper
5. Systematically map each ASBO attribute to the corresponding table column
6. Address any type incompatibilities using the Mutate Type feature
7. Verify all critical attributes are mapped (especially RN and RD)
8. Save the anchoring configuration
9. Test import a small set of resources to validate the mappings

Outcome: The ASBO is now anchored and ready for resource imports.

Scenario 2: Re-anchoring After Master Mapping Deletion¶

Situation: A master environment mapping was deleted, and the ASBO needs to be re-anchored.

Steps:

1. Verify that the ASBO shows as "unanchored" in the interface
2. Click the "Anchor" button (which becomes available again)
3. Select a datasource, schema, and table
4. In the Table Mapper, map columns to attributes
5. Note that you're creating a new master mapping with a potentially different structure
6. Complete the anchoring process
7. Consider re-importing existing resources to align with the new structure

Outcome: A new master environment mapping is created, and the ASBO is anchored again.

Scenario 3: Anchoring to a Database View¶

Situation: You need to anchor an ASBO to a database view rather than a base table.

Steps:

1. Ensure the database view exists and is accessible via the datasource
2. Click "Anchor" on the ASBO
3. Select the datasource and schema containing the view
4. In the table selection list, locate and select the view (views are typically marked with a special icon)
5. Review the view's column structure using the schema viewer
6. Open the Table Mapper and establish column-to-attribute mappings
7. Complete the anchoring process

Outcome: The ASBO is anchored to the view, and resource imports will execute queries against the view definition.

Scenario 4: Anchoring with Minimal Attribute Set¶

Situation: You want to anchor an ASBO but only map a subset of available columns.

Steps:

1. Begin the anchoring process as normal
2. In the Table Mapper, map only the essential columns:
3. Primary key column
4. Columns for RN and RD
5. Critical business attributes
6. Leave other attributes unmapped for now
7. Save the anchoring configuration
8. Test import resources to verify the minimal mapping works
9. Return later to add additional mappings as needed

Outcome: The ASBO is anchored with minimal mappings, allowing for incremental configuration.

Scenario 5: Anchoring with Type Transformations¶

Situation: Database column types don't match your desired logical types, requiring transformations.

Steps:

1. Begin the anchoring process and open the Table Mapper
2. Drag a column to an attribute and encounter a type incompatibility warning
3. Review the suggested type change carefully
4. If acceptable, click "Mutate Type" to apply the transformation
5. If not acceptable, consider:
6. Creating a database view with CAST or CONVERT operations
7. Modifying the ASBO attribute type manually before mapping
8. Using a different column that has the correct type
9. Repeat for each column requiring type handling
10. Complete the anchoring process after all transformations are resolved

Outcome: The ASBO is anchored with appropriate type mappings, either through mutations or database-level transformations.

Troubleshooting Anchoring Issues¶

No Datasources Available¶

Symptoms:

• Error message appears when clicking "Anchor"
• "No active datasources" warning displayed
• Cannot proceed to table selection

Resolution:

1. Navigate to the Datasources configuration section
2. Verify at least one datasource exists
3. Check that the datasource status is "Active" and "Online"
4. Test datasource connectivity:
5. Click "Test Connection" if available
6. Review connection parameters (host, port, database name)
7. Verify credentials are correct and not expired
8. If no datasources exist, create a new one:
9. Provide connection details
10. Test the connection
11. Activate the datasource
12. Return to the ASBO and retry anchoring

Schema or Table Lists Empty¶

Symptoms:

• Datasource is selected but no schemas appear
• Schema is selected but no tables appear
• Dropdown lists show "No items found"

Resolution:

1. Verify permissions:
2. Ensure the datasource credentials have SELECT permission on information schema
3. Check that the database user can enumerate schemas and tables

4. Verify no database-level restrictions on metadata access

5. Check datasource configuration:

6. Confirm the datasource is pointing to the correct database server
7. Verify the default schema or database is set correctly

8. Review any schema filtering or exclusion rules in the datasource settings

9. Test database access directly:

      -- Test schema access
      SELECT schema_name FROM information_schema.schemata;
   
      -- Test table access
      SELECT table_name FROM information_schema.tables WHERE table_schema = 'your_schema';
   

10. Refresh the datasource:

11. Navigate to datasource configuration
12. Click "Refresh Metadata" or "Reconnect"
13. Return to anchoring wizard and retry

Type Incompatibility Cannot Be Resolved¶

Symptoms:

• Repeated type mismatch warnings
• Mutate Type doesn't produce the desired result
• No compatible columns available for an attribute

Resolution:

1. Understand the root cause:
2. Review the column's actual data type in the database
3. Determine if the data can be safely converted to the desired logical type

4. Check if sample data matches the expected format

5. Database-level solutions:

      -- Create a view with type conversions
      CREATE VIEW compatible_table_v AS
      SELECT 
          CAST(varchar_column AS INTEGER) AS numeric_attribute,
          TO_DATE(string_date, 'YYYY-MM-DD') AS date_attribute,
          CAST(bit_column AS BOOLEAN) AS boolean_attribute
      FROM source_table;
   

6. ASBO-level solutions:

7. Modify the ASBO attribute type to match the column type
8. Add a transformation step in your data pipeline

9. Use middleware or ETL to pre-process data before import

10. Alternative approaches:

11. Map to a different column that has compatible type
12. Store the raw value and transform at the application level
13. Create a computed column in the database with the correct type

Drag and Drop Not Working¶

Symptoms:

• Columns cannot be dragged
• Drop zones don't activate
• No visual feedback during drag operations

Resolution:

1. Browser issues:
2. Refresh the browser page
3. Clear browser cache and cookies
4. Try a different browser (Chrome, Firefox, Edge recommended)

5. Disable browser extensions that might interfere with drag-and-drop

6. UI state issues:

7. Close and reopen the Table Mapper
8. Exit the anchoring wizard and start again

9. Log out and log back in to BizMetry

10. Data loading issues:

11. Ensure the table structure has fully loaded (watch for loading indicators)
12. Wait a few seconds after the interface opens before attempting drag operations

13. Check browser console for JavaScript errors

14. Alternative mapping method:

15. If drag-and-drop continues to fail, check if there's a manual mapping option
16. Some interfaces may provide dropdown-based mapping as an alternative

Anchoring Saves But Resources Won't Import¶

Symptoms:

• Anchoring completes successfully
• Import operations fail or return no data
• Error messages about missing columns or invalid mappings

Resolution:

1. Verify the master environment mapping:
2. Navigate to Env Mappings for the ASBO
3. Confirm the master mapping was created

4. Check that it points to the correct datasource/schema/table

5. Check attribute mappings:

6. Review each attribute in the ASBO configuration
7. Verify the column_metadata_name field is populated correctly

8. Ensure critical attributes (especially primary key) are mapped

9. Test datasource connectivity from import context:

10. The import process may use different credentials or connection pooling
11. Verify the agent or import service can reach the database

12. Check firewall rules and network connectivity

13. Review import logs:

14. Check detailed error messages in the import logs
15. Look for SQL errors, connection timeouts, or permission denials

16. Identify which specific column or query is failing

17. Validate data compatibility:

18. Query the table directly to ensure data exists
19. Check that data values are compatible with mapped types
20. Verify primary key values are unique and not null

Duplicate Attribute Names Causing Issues¶

Symptoms:

• Cannot create new attributes from columns
• Drop zone is always disabled
• Error about attribute name conflicts

Resolution:

1. Identify the conflict:
2. Review all existing ASBO attributes
3. Note which attribute name matches the column name

4. Determine if they should represent the same or different data

5. If they represent the same data:

6. Map the column to the existing attribute instead of creating new

7. Verify the existing attribute has the correct type

8. If they represent different data:

9. Rename the existing attribute to something more specific
10. Use the ASBO configuration editor to change the attribute name

11. Return to Table Mapper and create the new attribute

12. If using a view:

       -- Alias column to avoid naming conflict
       CREATE VIEW table_with_unique_names AS
       SELECT 
           existing_column AS existing_column_v2,
           -- other columns
       FROM source_table;
    

Cannot Remove Mappings¶

Symptoms:

• X button doesn't respond
• Mapping remains after clicking remove
• Error when trying to unmap

Resolution:

1. UI refresh:
2. Close and reopen the Table Mapper
3. Refresh the browser page

4. Try clicking the X button again

5. Check for dependencies:

6. Some mappings may be protected if used in RN/RD configuration
7. Verify the attribute isn't marked as required or locked

8. Check if the attribute is used in any business rules

9. Alternative approach:

10. Save the current state and exit Table Mapper
11. Edit the ASBO configuration directly
12. Remove the column_metadata_name value for the attribute
13. Return to Table Mapper to remap if needed

Impact of Anchoring on ASBO Lifecycle¶

Understanding how anchoring affects the ASBO throughout its lifecycle is important for effective management.

Structural Definition¶

Once anchored, the ASBO's structure is permanently defined by the table used during anchoring:

• Column snapshot: The structure reflects the table columns at the moment of anchoring
• Immutable base: This structure cannot be changed without re-anchoring
• Validation basis: All future environment mappings must match this structure

Environment Mapping Compatibility¶

After anchoring, any additional environment mappings you create must have table structures that match the anchored structure:

• Validation enforcement: BizMetry validates new environment mappings against the master structure
• Column matching: All columns from the master must exist in new environment tables
• Type compatibility: Data types must be compatible across environments

Resource Import Capability¶

Anchoring directly enables resource import functionality:

• Before anchoring: Cannot import resources from database
• After anchoring: Can import resources using the established mappings
• RN/RD configuration: Becomes possible only after anchoring

Anchoring vs. Environment Mapping¶

It's important to understand the distinction between these two related concepts:

Anchoring (Master Mapping Creation)¶

• Purpose: Initially links an ASBO to a physical table
• Occurs: Once, when first connecting an ASBO to a database
• Creates: The master environment mapping
• Defines: The canonical structure for the ASBO
• Requirement: ASBO must be unanchored

Environment Mapping (Additional Mappings)¶

• Purpose: Links the same ASBO to tables in other environments
• Occurs: Multiple times, after initial anchoring
• Creates: Secondary environment mappings
• Validates: Against the master structure
• Requirement: ASBO must already be anchored

Workflow Example:

1. DEV Environment: Anchor ASBO to dev_db.clients table (creates master mapping)
2. QA Environment: Create env mapping to qa_db.clients table (validates against master)
3. PROD Environment: Create env mapping to prod_db.clients table (validates against master)

Related Topics¶

• Anchoring Concept & Table Selection Wizard
• The Table Mapper
• Understanding Environment Mappings
• Creating a New Environment Mapping
• Editing an Environment Mapping
• Deleting an Environment Mapping
• Importing Resources from Database
• Configuring Resource Name (RN) and Resource Description (RD)
• Configuring Datasources
• Managing Environments
• Resource Type Configuration
• Troubleshooting Import Issues