Home Goals / OKRs Goals Import via CSV (V2)

Goals Import via CSV (V2)

Last updated on Sep 05, 2025

This article explains how to create, edit, and delete goals in Peoplebox using CSV/XLSX upload. It covers file formats, mandatory columns, goal actions, milestone rules, and review cycle requirements.

1. 📂 File Format

  • Supported formats: CSV, XLSX

  • Row limit: No strict limit.

    • Large CSV files may take longer to process, especially if errors are present.

2. 📑 Column Definitions

  • Row ID: Unique identifier for each row.

  • Parent Row IDs: Row ID(s) of parent goal(s) within the same upload. Accepts multiple IDs separated by commas.

  • Parent Goal IDs: Goal ID(s) of existing parent goals already in the system. Accepts multiple IDs separated by commas.

  • Goal ID: Leave blank when creating a new goal. Mandatory for Edit or Delete actions. Only one value is allowed.

  • Action: Supported values: Edit, Delete. Leave blank for creating new goals. Any other value will throw an error.

  • Goal Title: Title of the goal.

  • Owner Emails: Comma-separated list of owner email addresses.

  • Goal Cycle: Select from cycles available in the UI (e.g., Monthly, Quarterly, Annually).

  • Goal Type: Goal measurement type. Supported values: Default Progress, Binary, Number, Custom Percent, Euro, Dollar, etc.

  • Scope: Goal scope: Individual, Department, Company.

  • Departments: Department name(s), case insensitive.

  • Start Date: Start date of the goal.

  • End Date: End date of the goal.

  • Description: Description of the goal.

  • Starting Value: Initial value of the goal.

  • Target Value: Target value of the goal.

  • Current Value: Latest check-in value.

  • Progress Status: Must match progress options available in the UI.

  • Check-in Type: Progress tracking method: Auto Rollup, Manual, or External Source.

  • Tags: Assign tag(s) to a goal. If multiple, separate with commas.

  • Review Cycle ID: Review cycle ID if linking to a review cycle.

  • Review Cycle Weightage: Goal weightage (%) in the review cycle.

  • Approved: TRUE or FALSE — indicates manager approval.

  • Custom Visibility Employees: Comma-separated list of employee emails for custom visibility.

  • Custom Visibility Departments: Comma-separated list of department names for custom visibility.

  • Milestone Summary Method: Method for milestone progress calculation: Sum, Average, Last Value.

  • Milestone Progress Targets: Milestone targets in a-b,c-d format. Example: 25-50,75-100.

  • Has Milestones: TRUE or FALSE — whether the goal has milestones.

  • Integration Config: Configuration details (JSON) required to connect a goal with an external data source for auto-sync. This config enables Peoplebox to fetch and sync goal data automatically from that source.

3. 🎯 Goal Actions

✅ Creating a Goal

  • Leave Goal ID and Action blank.

  • Mandatory fields: Row ID, Goal Title, Owner Emails, Goal Cycle, Type, Scope, Visibility

  • Optional fields: Start/End dates, Description, Starting Value, Target Value, etc.

Use Cases:

  1. Standalone Goal (no parent or child alignment): Only mandatory fields required.

  2. Key Results (KRs) for a Parent Goal created in the same upload:

    • Fill in Parent Row ID of the KR.

    • The value must match the Row ID of the parent goal in the same file.

  3. Aligning a Goal to an Existing Goal in the System: Provide the Parent Goal ID.

✏️ Editing a Goal

  • Set Action = Edit.

  • Always include the Goal ID of the goal you want to edit.

  • Provide only the column(s) you want to update (in addition to Goal ID and Action).

❌ Deleting a Goal

  • Set Action = Delete.

  • Always include the Goal ID of the goal to delete.

  • No other fields required (even if extra fields are provided, they will be ignored).

Special Cases:

  • Deleting a Key Result (KR): Provide KR’s Goal ID + Action = Delete.

  • Deleting a Parent Goal with multiple KRs: Provide Goal ID of the parent + Action = Delete.

    • ⚠️ Associated KRs will not be deleted automatically. Each KR must be deleted separately.

4. 📊 Milestone Rules

  • Monthly Cycle:

    • Milestone Split Type must be left blank.

    • Any value entered will throw an error.

  • Quarterly Cycle:

    • Milestone Split Type can be Monthly (3 milestones).

  • Annual Cycle:

    • Milestone Split Type can be:

      • Monthly (12 milestones), OR

      • Quarterly (4 milestones).

  • Milestone Progress Targets:

    • Format: a-b,c-d

    • Example: 25-50,75-100.

5. 🔄 Review Cycle Rules

  • Only Admins can upload review cycle goals.

  • Validation depends on goal configuration in the Review Cycle (RC):

    • Goals with Key Results: Upload must contain only KRs.

    • Goals without Key Results: Upload must contain only Goals.

  • If a non-admin uploads rows with Review Cycle ID → those rows will fail.

Review Cycle Weightage:

  • If weightage does not sum to 100%:

    • ✅ Upload will be marked Done if the approval phase exists.

    • ❌ Upload will remain Undone if no approval phase is configured.

  • Missing weightage can be resolved by:

    • Admin uploading additional goals, OR

    • Manager adjusting via UI, OR

    • Reviewee adjusting via UI.

6. 📝 Additional Notes

  • Company-level goals:

    • Only Admins or users with the Custom Role (Admin permission) can create them.

    • Only Admins, goal owners, or managers of the goal owners can edit/delete them.

  • Owner Emails: Must be valid email IDs.

  • Duplicates: Re-uploading the same file multiple times will create duplicate records.