Ironclad Repository to Entities Migration Guide

Overview

This guide provides a comprehensive overview of the steps required to effectively plan and implement the migration of your counterparty data from the Ironclad Repository to the new Entities framework. Historically, customers have managed counterparty data within the repository as a related record to workflows. With the introduction of the new Entities framework, Ironclad customers now have the flexibility to separate their counterparty data from the repository, enabling them to be mapped to workflows by the counterparty object. Although there isn’t currently an automated way to complete this migration, this sequence of steps will help Ironclad customers plan and execute an effective migration strategy.

Phase 1: Planning & Preparation

1.1 Assess Current State

• Inventory existing counterparty records in the repository
• Document current workflow dependencies
• Identify custom fields and metadata that need migration
• Note any integrations that rely on counterparty data

1.2 Define Migration Scope

• Determine which counterparty records to migrate
• Establish timeline and resource allocation
• Identify stakeholders and communication plan
• Create backup of existing data

1.3 Create Migration Checklist

• All counterparty records identified
• Custom fields mapped to entity properties
• Workflow dependencies documented
• Testing environment prepared
• Rollback plan established

Phase 2: Configure Entity Settings

This configuration step presents a valuable opportunity to not only map your existing entity properties to Ironclad's schema, but also to clean up and optimize your counterparty data during the migration process. Take advantage of this moment to standardize naming conventions, consolidate duplicate entries, validate data completeness, and establish consistent formatting rules that will improve data quality across both systems going forward

2.1 Set Up Entity Relationship Types

Before creating entities, configure the relationship framework that will define how entities interact with each other and with records.

Steps:

1. Navigate to Company Settings → Entities
2. Click on Relationship Types
3. Define relationship types that match your business needs:
   • Vendor/Customer relationships
   • Partner relationships
   • Custom relationship types

Reference: Create & Manage Relationship Types and Entity Properties

2.2 Configure Entity Permissions

Establish proper access controls to ensure data security and compliance.

Permission Levels to Configure:

• View permissions: Who can see entity data
• Edit permissions: Who can modify entity information
• Create permissions: Who can create new entities
• Delete permissions: Who can remove entities

Steps:

1. Go to Company Settings → Groups → Configure Group → Repository and Entities
2. Configure access controls

Reference: Entity Permissions Overview

Phase 3: Export & Transform Data

3.1 Export Counterparty Records

Export Process:

1. Navigate to the Repository
2. Apply filters to select counterparty records
3. Export records to spreadsheet format
4. Include all relevant metadata and custom fields

3.2 Data Transformation Checklist

Prepare your exported data for entity import:

• Remove duplicate entries
• Standardize naming conventions
• Validate required fields are populated
• Format dates consistently (MM/DD/YYYY or DD/MM/YYYY)
• Clean up special characters
• Add entity relationship columns if needed

Phase 4: Create Entities

4.1 Import Transformed Data

Import Steps:

1. Navigate to Entities section
2. Click Import Entities
3. Upload your prepared spreadsheet
4. Map spreadsheet columns to entity fields
5. Review mapping and validate data
6. Execute import

Best Practices:

• Start with a small batch (10-20 records) for testing
• Verify import results before proceeding with full dataset
• Document any import errors for troubleshooting

References: Create Entities from Existing Data
Update Entity Data Using Metadata Export and Import

4.2 Verify Entity Creation

• Confirm all entities imported successfully
• Check that custom properties populated correctly
• Validate entity relationships are established
• Review any import warnings or errors

Phase 5: Connect Entities and Records

5.1 Choose Connection Method

5.2 Method 1: AI Suggestions (RunAI) - Recommended

For batch processing of entity connections:

1. Navigate to the Records section
2. Select records that need entity connections
3. Click Run AI Suggestions
4. Review AI-suggested entity matches
5. Approve or modify suggestions
6. Apply connections in batches

Benefits:

• Faster processing for large volumes
• Pattern recognition for accurate matching
• Batch approval capabilities

Reference: Use AI Suggestions to Tag Entities on Records

5.3 Method 2: Metadata Import

For structured bulk connections:

1. Prepare a CSV with:
   • Record IDs
   • Entity IDs or names
   • Connection type
2. Navigate to Import → Metadata Import
3. Upload connection mapping file
4. Validate and execute import

Reference: Connect Entities and Records

5.4 Method 3: Ironclad API - For Automated Integrations

For programmatic bulk operations and system integrations:

The Ironclad API provides comprehensive endpoints for entity management and connection operations. This method is ideal for organizations with technical resources who need to automate the migration process or integrate with other systems.

Available API Endpoints:

Implementation Steps:

1. Authentication Setup
   • Generate API credentials in Ironclad settings
   • Configure authentication headers
   • Test connection with a simple GET request
2. Bulk Entity Creation

# Example: Create entities via API
  POST /public/v1/entities
     {
     "name": "Acme Corporation",
     "type": "vendor",
     "properties": {
       "industry": "Technology",
       "location": "San Francisco"
     }
   }

3. Establish Entity-Record Connections

   • Query existing records via API
   • Map record IDs to entity IDs

   Reference: Entity References in Workflows and Records

4. Validation

   • Use GET endpoints to verify entity creation
   • Confirm relationship mappings

Requirements:

• Technical expertise (developers/IT team)
• API access permissions
• Programming knowledge (Python, JavaScript, etc.)
• Error handling and retry logic implementation

Reference: Ironclad API Developer Documentation

Reference: Connect Entities and Records - All Methods

5.5 Method 4: Manual Linking

For complex or one-off connections:

1. Open individual record
2. Navigate to entity connection field
3. Search and select appropriate entity
4. Save connection

Phase 6: Update Workflow Configuration

6.1 Workflow Migration Strategy

6.2 Update Workflow Designer

Steps for each affected workflow:

1. Open Workflow Designer
2. Navigate to counterparty lookup fields
3. Change field type from "Related Record" to "Entity Lookup"
4. Configure entity lookup settings:
   • Select entity type
   • Set search parameters (note: search/filter parameters are more robust for entity object compared to related records)
   • Update any dependent logic

6.3 Update Workflow Components

Components to review and update:

• Forms: Update counterparty selection fields
• Approvals: Modify routing based on entity properties
• Integrations: Update API calls to use entity IDs
• Reports: Adjust to pull from entity data
• Notifications: Update merge tags for entity fields

Reference: Configure Entities in Workflow Designer

Phase 7: Validation & Testing

7.1 Testing Checklist

Data Validation:

• All counterparty records successfully migrated to entities
• Entity relationships correctly established
• Custom properties populated accurately
• No data loss or corruption
• Record → Entity mappings are correct

Workflow Testing:

• Entity lookups function correctly
• Workflow routing works as expected
• Integrations properly handle entity data
• Reports display accurate information

7.2 User Acceptance Testing

1. Select test users from different departments
2. Provide test scenarios covering common use cases
3. Document feedback and issues
4. Address concerns before full rollout

7.3 Performance Validation

• Monitor system performance post-migration
• Check query response times
• Verify bulk operations efficiency
• Ensure no degradation in user experience

Phase 8: Go-Live & Post-Migration Activities

8.1 Communication & Training

1. Announce completion to all stakeholders
2. Provide training on new entity features
3. Share documentation and quick reference guides
4. Establish support channels for questions

8.2 Monitoring & Optimization

• Track entity usage patterns
• Gather user feedback
• Optimize entity search and filtering
• Refine permissions as needed

8.3 Documentation

• Update internal process documentation
• Record lessons learned
• Create troubleshooting guide
• Document custom configurations

Support Resources

• Ironclad Support Center
• Ironclad Professional Services for complex migrations
• Ironclad Partner Ecosystem

Conclusion

Successfully migrating from repository-based counterparty management to the Entities framework requires careful planning, systematic execution, and thorough testing. By following this guide and leveraging the provided resources, you can ensure a smooth transition that enhances your contract management capabilities while maintaining data integrity and workflow continuity.

Remember that this migration is not just a technical upgrade but an opportunity to optimize your counterparty data management, improve workflow efficiency, and enable more sophisticated reporting and analytics capabilities.