Skip to main content
Planview Customer Success Center

API and Data Import for Financial Entries

There is an API and a data import facility for importing entries for both forecasts and actuals. Entries will be associated with a project, and can be associated with tasks.

Using the API

The standard PPM Pro methods for creating and updating entities now support the FinancialEntry entity type (ID=300). In addition, there are 2 new API calls for contours:

  • getFinancialEntryContour - Retrieves the full financial entry contour, or optionally, the contour between the specified date range.
  • allocateFinancialEntryContour - Creates a custom contour for specific month.

Use the Admin/Web Services API page to find the fields defined for the financial entry entity (will display both UDFs and standard fields) by clicking the Fields link. Pick the tab for the type of call (Select/Insert/Update) and locate the fields and their IDs. Note the Is Required column, and be sure to include value pairs for those fields as necessary.

wsapi_fields.png

API Notes
selectEntity

Requires an entity ID. Returns core set of metadata (not all metadata) for specified entity. if you want specific metadata, must have a fieldsRequest ID for each field you want returned.

findEntity

Use the financial entry entity type ID = 300.

Returns all financial entries (actuals and forecasts) if no value pair(s) included.

If you want to see just actuals or just forecasts, for example, then a value pair must be passed for either financial entry type, or a parent type (if parent type is project, returns forecasts; if parent is forecast, returns actuals).

insertEntity

The Parent Entity Type ID determines whether to create an actual or a forecast. If the parent entity is a project, then the entity type to insert is a forecast. If the parent entity type is a forecast, the entity type to insert is an actual. Requires parent entity ID along with type ID.

Actuals/Forecast Amount required - can be 0.

Use Forecast Amount (ID 30050) for inserting forecasts, and use Actuals Amount (ID 30056) for inserting actuals.

If no To Date included, then lump sum entry on From Date. If To Date included, automatic (even) monthly contours created between From/To dates.

updateEntity Same as insertEntity.
deleteEntity Forecast entries cannot be deleted if there are associated actuals. 
getFinancialEntryContour Retrieves the full financial entry contour, or optionally, the contour between the specified date range.
allocateFinancialEntryContour Inserts contours across the specified data range for a forecast or an actuals entry

Data Import

Forecasts and Actuals have been added to the list of entities on Admin/Data Import. You import each type of entry separately. Forecasts are associated with a parent project when imported, while actuals are associated with a parent forecast entry. You must create the forecast entries before importing the actuals. 

As with other entities, you can use the Generate Import File button to generate an Excel template that you can use to import the data for creating (New) or updating (Update) financial entries. Once you fill out the spreadsheet and save, you select the entity data type to import from the list and click the Import button, following the instructions for mapping fields (including UDFs) and importing the data. 

Financial Entries Import Notes
  • Both forecast entries and actuals entries require a parent ID (see Using the ID Inspector for instructions for obtaining entity IDs):
  • Forecast entries need a parent project ID. You can usually find the project ID on the project Details section, or, you can use the ID Inspector from the projects List page.
  • Actuals entries need a parent forecast entry ID. If you did not include the ID field on the Financial grid, you can find the forecast entry ID by using the ID Inspector. 
  • Forecasts require a Category ID. This ID can be found using the ID Inspector on Admin/Setup/Financial Entries/Categories
  • Date format is mm/dd/yyyy
  • If you enter a From Date with no To Date, then the amount is considered a lump sum on the From Date.
  • If a To Date is provided, then the amount is distributed evenly (monthly) between the From and to Dates.
  • If contours are provided (see next bullet) that extend beyond an included To Date, the To Date will be updated to reflect the last contour date
  • You can import a list of monthly values (contours) separated by the ';' (semicolon) character. Each value in the list must be a number, the word "null", or a sequence of zero or more spaces.
    • Values are entered in a semicolon-delimited field.
    • Decimal separator can be period ('.') or comma (',')
    • Do not enter grouping characters
    • Do not enter currency symbols.
    • The following list is valid: 100; 100, ;100.;1500.50;;null;1500,50;; ;30
    • The following values are not valid: 1,500.00;1.500,00
  • The Labor field takes the values Yes, No, True, False