Migrate from Timefold to HubSpot

Timefold tenants represent organizational units in the planning platform. Each tenant maps to one HubSpot Company record as the top-level organizational container. Multi-tenant hierarchies (parent/child tenants) map using HubSpot's parent company field. Tenant metadata (created date, subscription tier) migrates as custom properties on the Company record.

Timefold members are the human users or resources who receive shift assignments and route plans. Each member becomes a HubSpot Contact with name, email, phone, and role information preserved. Member status (active/inactive) and member type (employee, contractor) become HubSpot Contact custom properties.

Timefold roles define access permissions and skill designations for members within a tenant. Roles map to HubSpot Teams for permission grouping, with role names and skill tags preserved as team description fields or custom properties. Complex multi-skill role definitions that exceed HubSpot Teams scope are surfaced as additional custom Contact properties.

Timefold models define the type of optimization problem (field service routing, shift scheduling, vehicle routing). These have no direct HubSpot equivalent, so we create a Timefold_Model custom object to store model name, model type, constraint count, and planning horizon as custom properties. The custom object provides a reference catalog for all migrated plans.

A Timefold plan is the solver output at a point in time — shifts assigned, routes sequenced, score calculated. We create a Timefold_Plan custom object holding the plan name, model reference, plan timestamp, solver score (parsed into hard/medium/soft components), and links to associated shift and route records. Plans are historical snapshots, not live solver state.

Shift planning entities represent work blocks assigned to members. These map to HubSpot Tasks with custom properties for shift start time, end time, location, required skills, and assigned member lookup. Task subject carries the shift identifier; task status reflects completion state from the source plan.

Route planning entities in field service models represent vehicle or technician routes. HubSpot has no native route object, so we create a Timefold_Route custom object with stops (as line items or related custom records), vehicle reference, total distance, and route sequence. Route status and score contribution are preserved as custom properties.

Timefold locations (depots, customer sites, job addresses) used as planning problem facts map to HubSpot Company records. Address, name, and location type (depot, customer, waypoint) are preserved. Locations used in route plans are linked to the relevant route via custom object associations.

Vehicles used in routing models represent assets or resources available for assignments. These map to HubSpot Deals with custom properties for vehicle ID, capacity, skills, and availability windows. The Deal object provides a natural container for vehicle-specific data and can link to associated route records.

Timefold constraint rules (hard, medium, soft) with weight values have no HubSpot equivalent. We store constraint names, types, and weights as custom properties on the Timefold_Plan custom object. Constraint builders (DRL expressions, nearby selection rules) are preserved as long-text reference fields for rebuild planning.

Timefold solver scores follow the format 0hard/-257medium/-6119520soft. We parse these into three separate custom number fields on the Timefold_Plan object: Score_Hard__c, Score_Medium__c, and Score_Soft__c. This enables reporting and filtering in HubSpot without parsing the composite string. Each score component can then be used individually in HubSpot workflow conditions, list filters, and dashboard visualizations for plan quality analysis.

The solver assigns members to shifts as a core planning variable. In HubSpot, each Task carries an assigned-owner link to the corresponding Contact record. The assignment timestamp and any override flags are stored as custom properties on the Task for audit continuity.