It is important to setup the Financial Plan in OnePlan correctly before you start importing data from your source file. It is equally import to ensure that all required data fields are provided in the source file in the format expected.

Best Practices

• The first column in your CSV should be the Plan External Id field. 
• Use global cost categories if possible as custom cost categories exist only on the plan level and makes comparing financial data more difficult.
• Use detail rows only if you need the extra detail. If you use detail rows, remember that they roll up. You will not be able to set a different value on the parent cost category.
• The default time phasing period is monthly. Use the weekly option only if it is absolutely necessary.
• When you are using monthly time phasing, use the first of the month to store your data.
• As the integration updates data, pass in 0 if you want to "remove" existing cost.
• Always provide consistent External Ids to avoid duplicate records
• Use Cost Type Name unless strict ID matching is required
• Include Cost Name when creating new categories
• Validate parent-child relationships before importing
• Ensure custom field names match exactly
• Test with a small dataset before full import

Financial Plan Settings

Setting Up Plan External Id

In order to identify a plan, there must be a unique ID configured in OnePlan. If you don't have this setup already, please follow these steps:

1. Create custom plan field if you don't have one already for a unique ID:
   1. In OnePlan, go to an Area's List view (e.g. Enterprise Portfolios). 
   2. Click Columns.
   3. Click Add Field > Enterprise Field.
   4. Name the field (e.g "Plan External Id").
   5. Set the field type to Text. 
   6. Click Save.
2. Select Custom Field for Financial Import
   1. In OnePlan go to Settings (gear icon). 
   2. Go to Financial Plan > Import.
   3. Use the External Id Field dropdown to select your new custom field.
   4. The selection saves automatically. 

Setting up Cost External Ids

Cost external IDs are used to specify the cost category in the source file.

To configure external IDs for your global cost categories, please do the following: 

1. Navigate to the Admin pages.
2. Access Financial Plan section.
3. Select Cost Categories.
4. Find your cost category and click on the edit (paper and pencil) icon.
5. Enter a unique External Id and Save.

Please note that when adding new cost categories via the UI, there is no automatically generated External Ids, one must be manually entered. Possible External Ids can be letters, numbers, or a mix of the two.

Cost Type Name vs Cost Type Id

The integration uses cost types (such as Budget, Forecast, and Actuals) to determine where financial values are written.

However, it’s important to understand that Financial Plan Cost Types and Resource Cost Types are stored in the same underlying table.

Why This Matters

Because these cost types share the same table:

• It is possible for a Resource Cost Type and a Financial Plan Cost Type to have the same name
• When this happens, using Cost Type Name can result in ambiguity
• The integration may not reliably determine which cost type to use

When to Use Cost Type Name

Use Cost Type Name when:

• You are confident there are no duplicate names across Resource and Financial Cost Types
• You want a more readable and user-friendly configuration

When to Use Cost Type Id (Recommended in Complex Scenarios)

Use Cost Type Id when:

• There are duplicate or similar cost type names in your environment
• You are working with both Resource Planner and Financial Planner data
• You want to ensure the value is written to the exact correct cost type

Using Cost Type Id removes any ambiguity and guarantees that data is written to the intended destination.

Recommendation: If there is any overlap between Resource and Financial Plan Cost Type names in your environment, it is strongly recommended to use Cost Type Id to avoid unexpected behavior.

Custom Cost Categories

If you have a wide range of cost categories and some of them apply to only specific plans, you can use custom cost categories that exist only for individual plans. You have to enable this feature in order to use it. 

Please follow these steps to enable custom cost categories:

1. In the OnePlan admin pages, navigate to Financial Plan, and click on Advanced.
2. Check the box labelled Allow Plan Level Cost Categories. 

If you don't want to use custom cost categories, please check the Do not create custom cost categories for plans checkbox during the setup. 

If you don't use custom cost categories and your source file includes cost categories that are not in OnePlan already, then those records will be skipped as they cannot be imported.

Creating New Custom Cost Categories

If a row contains a Cost External Id that does not match an existing cost category, the integration will create a new cost category (if enabled in the configuration).

When Cost Name is NOT Provided

If Cost Name is not included in the import:

• A new cost category is created, however the value residing within the CSV field Cost External Id is used as the category name in the Financial Planner. 

This behavior works well when the Cost External Id is the same as the desired display name (Cost Category). However, in many cases, it may not be user friendly or suitable as a display name. 

When Cost Name IS Provided

If Cost Name is included:

• A new cost category is created
• The cost Name is used as the display name (Cost Category) in the Financial Planner
• The Cost External Id is still used as the unique identifier behind the scenes. 

Best Practice

• Always include Cost Name when creating new cost categories unless:
  • Your Cost External Id values are already user-friendly and intended for display

Creating a Custom Cost Category Under an Existing Category

The Parent Cost External Id is only used when creating new custom cost category that should be placed (as a child cost category) under an existing cost category. 

Behavior

If the Cost External Id already exists:

• The integration updates the existing cost category

If the Cost External Id does NOT exist (a new category is being created for that plan):

• If Parent Cost External Id is provided:
  • The new cost category is created as a child of that specified parent. 
• If Parent Cost External Id is NOT provided:
  • The new cost category is created at the top (root) level

Best Practice

Use Parent Cost External Id only when:

• Creating new (custom) cost categories
• You want to control where they appear in the hierarchy

Do no rely on this field when updating existing categories. 

Custom Fields

For the integration to write to a custom field in the financial planner, the custom field must first exist in OnePlan. To create custom fields for the financial planner:

1. Navigate to the OnePlan Admin page, select the Financial Plan section.
2. Expand the Fields section.
3. Click on Custom Fields +.
4. Provide a Name and Field Type.
5. Click ADD.

Writing to Custom Fields

Requirements

• The custom field must already exist in OnePlan
• The column name in your file must exactly match the field name
  • Choice fields can use the front-end option name and does not require a GUID Id. 

Behavior

• Custom fields are not mapped manually in the integration
• Matching is done automatically based on column name

Detail Rows

Detail rows allow more granular financial tracking under a cost category.

Required Fields

To use detail rows, include:

• Use Detail Row = Yes
• Detail Row External Id

Behavior

• If the detail row exists → it is updated
• If it does not exist → it is created

Important Notes

• Detail rows roll up to their parent cost category
• Values at the detail row level contribute to totals
• You cannot directly override parent totals when using detail rows.
• You should not add detail rows on top of custom cost categories, one or the other should be used, not both.
• Detail rows do not have a cost name associated to them. The title/name will remain blank in the Financial Planner. 

Source Data

How the Import Works

 For each row in the source file, the integration processes data in the following order:

1. Identify the target plan using Plan External Id 
2. Identify the cost category using Cost External Id 
3. Determine whether to: 
   • Update an existing cost category 
   • Create a new cost category 
   • Write to a detail row 
4. Apply the cost value for the specified Cost Date and Cost Type 

Understanding this flow is key to correctly structuring your data.

Required & Optional Fields

Mandatory Fields (Always Required)

The Following fields must be present in every import:

Conditionally Required Fields

These fields are required depending on the scenario:

Example Data

CSV File

How the data is prepared in the CSV file

How Data Imports into OnePlan

Above is an example of how the data will appear within the Financial Planner based on the information set within the CSV. 

Strategies

CostImportToFinancialPlanner

The only strategy is the CostImportToFinancialPlanner that executes the import logic. You can run this on a schedule or on demand, manually. 

Mind the Gap

• This integration only import financial data into OnePlan. If you want to export financial data, use our OneAnalytics integration to do that.
• This integration is designed to import time phased data into OnePlan. If you want to import only rolled up numbers like a single "budget" per plan, then use our plan import integration.
• For all custom Cost Categories that are created by this integration, those Cost Categories are only created for the specific plan the data is being written to. This integration will not create Cost Categories at the global level.

• Financial Plan Template Detail Rows Sample.csv334 Bytes