upsert_financial_plan

[LOCAL — SOAP financial plan write. No Beta MCP equivalent exists.]

Upsert (create or update) a financial plan using SOAP FinancialPlanService.

Creates or updates a financial plan in Planview Portfolios using the SOAP API. This is a single-line update tool optimized for simple use cases.

Args: plan_data: Financial plan data dictionary. Required fields: - Key: Financial plan key URI (e.g., "ekey://12/MyPlan") OR - EntityKey: Entity key URI (e.g., "key://2/$Plan/17286") AND - VersionKey: Version key URI (e.g., "key://14/57") - Lines: List of FinancialPlanLineDto dictionaries Each FinancialPlanLineDto requires: - AccountKey: Account key URI (e.g., "key://2/$Account/13607") - Unit: Unit type ("Currency", "Units", "Unit Cost", "Unit Price", "FTE", "Hours") - Entries: List of EntryDto dictionaries - CurrencyKey: Currency key URI (defaults to "key://1/USD" if not provided) - Attributes: Optional list of LineAttributeDto dictionaries Each EntryDto requires: - PeriodKey: Period key URI (e.g., "key://16/197") - Value: Numeric value

Returns: Dict with: - success: True if operation succeeded - data: Financial plan DTO (may have empty Lines array - this is normal SOAP API behavior) - warnings: List of non-fatal warnings (e.g., "InvalidStructureCode", "InvalidDefaultValues")

Note: The SOAP API may return empty Lines array in the response even though data was persisted.
This is expected behavior - use read_financial_plan() to verify the data was saved.

Raises: PlanviewValidationError: If plan data is invalid PlanviewAuthError: If authentication fails PlanviewError: For other errors

Examples: Minimal (single line, single period): { "EntityKey": "key://2/$Plan/17286", "VersionKey": "key://14/57", "Lines": [{ "AccountKey": "key://2/$Account/13607", "Unit": "Currency", "CurrencyKey": "key://1/USD", "Entries": [{ "PeriodKey": "key://16/197", "Value": 10000 }] }] }

Using existing plan Key:
    {
        "Key": "ekey://12/MyPlan",
        "Lines": [{
            "AccountKey": "key://2/$Account/13607",
            "Unit": "Currency",
            "Entries": [{
                "PeriodKey": "key://16/197",
                "Value": 10000
            }]
        }]
    }

Notes: - Field names must use PascalCase (e.g., AccountKey, not account_key) - Only changed or added lines must be sent - AccountKey and PeriodKey must match Planview configuration - Unit types: "Currency", "Units", "Unit Cost", "Unit Price", "FTE", "Hours" - For new projects, the financial plan may not exist yet - upsert will create it

Common Errors and Solutions: - "No editable lines were provided": The account/period keys don't match the model. Solution: Use discover_financial_plan_info() or read_financial_plan() to find valid keys. - "Account not found in model": The specified account doesn't exist for this version. Solution: Use discover_financial_plan_info() with a reference project to discover valid accounts. - "Unable to find the requested Financial Plan": Plan doesn't exist (common for new projects). Solution: Use upsert_financial_plan() directly - it creates the plan if needed.

Known SOAP API Behaviors: - Response may show empty Lines array: The SOAP API doesn't always echo back the full payload. This is normal - the data IS persisted. Use read_financial_plan() to verify. - Warnings are non-fatal: Warnings like "InvalidStructureCode" or "InvalidDefaultValues" indicate configuration issues but don't prevent successful creation. Check the warnings array in the response for details.