Plugins Overview

Project Notes XML

Nearly all information found in Project Notes can be exported or imported using XML. The best way to understand the XML format is to export it. The format is based around a tree structure described below. XML files can be used to easily exchange information with other Project Notes users. Plugins can read and write records in this format with data.exportXml() and data.importXml(). To export a file, choose Export XML… from the app menu (the menu icon at the top of the icon rail), or use the Export XML action on a record's detail page or right-click menu.

The XML format:

<?xml version="1.0" encoding="UTF-8"?>
<projectnotes filepath="C:UsersMyAccountOneDriveProject NotesMyDatabase.db" export_date="09/22/2020 12:38 PM" filter_field="project_id" project_manager_id="159709810500028597" managing_company_id="{ba96fb89-6c2d-46db-864c-5be6292b1045}" managing_company_name="My Company, Inc." managing_manager_name="My Name" filter_values="{ba96fb89-6c2d-46db-864c-5be6292b10ef}">
 <table name="projects" filter_field_1="project_id" filter_value_1="159709812400019208">
  <row delete=true>
   <column name="project_id">{ba96fb89-6c2d-46db-864c-5be6292b10e4}</column>
   <column name="project_number">P4000</column>
   <column name="project_name">IT New Server Install</column>
   <column name="last_status_date">09/02/2020</column>
   <column name="last_invoice_date">09/02/2020</column>
   <column name="primary_contact" lookupvalue="Jim Smith">{ba96fb89-6c2d-46db-864c-5be6292b10e4}</column>
   <column name="budget">$2090.00</column>
   <column name="actual">$649.00</column>
   <column name="bcwp">$649.00</column>
   <column name="bcws">$2090.00</column>
   <column name="bac">$2090.00</column>
   <column name="invoicing_period">Monthly</column>
   <column name="status_report_period">None</column>
   <column name="client_id" lookupvalue="Special Law Firm">{ba96fb89-6c2d-46db-864c-5be6292b10gg}</column>
   <column name="project_status">Active</column>
   <table name="status_report_items" filter_field="project_id" filter_value="159709812400019208"/>
   <table name="project_people" filter_field="project_id" filter_value="{ba96fb89-6c2d-46db-864c-5be6292b10ef}">
    <row>
     <column name="project_people_id">{ba96fb89-6c2d-46db-884c-5be6292b10eo}</column>
     <column name="project_id" lookupvalue="P4000">{ba96fb89-6c2d-46db-864c-5be6292b10ef}</column>
     <column name="project_name" lookupvalue="IT New Server Install">159709812400019208</column>
     <column name="people_id" lookupvalue="Mike Smith">{7e6df350-ab03-4653-99f1-7abb09bbefa3}</column>
     <column name="role"></column>
     <column name="receive_status_report"></column>
     <column name="name">Mike Smith</column>
     <column name="email">Mike.Smith@mycompany.com</column>
     <column name="client_name">My Company, Inc.</column>
    </row>
    <row>
     <column name="project_people_id">159907543300015593</column>
     <column name="project_id" lookupvalue="J2627">{7e6df350-ab03-4653-99f1-7abb09bbefa3}</column>
     <column name="project_name" lookupvalue="IT New Server Install">159709812400019208</column>
     <column name="people_id" lookupvalue="Jim Smith">{92ce1e4e-a908-4f6c-8348-c85beb459942}</column>
     <column name="role">Lead Support</column>
     <column name="receive_status_report">1</column>
     <column name="name">Jim Smith</column>
     <column name="email">jim_smith@speciallawfirm.com</column>
     <column name="client_name">Speical Law Firm</column>
    </row>
   </table>
   <table name="project_locations" filter_field="project_id" filter_value="{7e6df350-ab03-4653-99f1-7abb09bbefa3}">
    <row>
     <column name="project_location_id">{7e6df350-ab03-4653-99f1-7abb09bbefa3}</column>
     <column name="project_id" lookupvalue="P4000">{56601f6b-30d9-4fc0-a7e1-d367d30a4e52}</column>
     <column name="location_type">PDF File</column>
     <column name="location_description">Quote : Project Quote.pdf</column>
     <column name="full_path">P:ProjectFolderP4000_IT New Server InstallQuotesQT9876908.pdf</column>
     <column name="project_name" lookupvalue="IT New Server Install">{3d9f88d9-810b-4e6c-827b-9afeef0dd48f}</column>
    </row>
   </table>
   <table name="project_notes" filter_field="project_id" filter_value="{3d9f88d9-810b-4e6c-827b-9afeef0dd48f}"/>
   <table name="item_tracker" filter_field="project_id" filter_value="159709812400019208"/>
  </row>
 </table>
</projectnotes>

Audience groups in a project export

Exporting a project includes its saved report and meeting audience groups. Each group is a <row> in a <table name="project_email_audiences"> nested inside that project's <row>. Importing the project XML also imports these rows. A project with no saved groups has an empty audience table.

For example, this table can appear alongside the other child tables in a project row:

<table name="project_email_audiences" filter_field_1="project_id" filter_value_1="project-uuid">
 <row>
  <column name="id">audience-uuid</column>
  <column name="project_id" lookupvalue="P4000">project-uuid</column>
  <column name="workflow">project</column>
  <column name="audience_name">Project team</column>
  <column name="people_source">project-team</column>
  <column name="company_filter">all</column>
  <column name="selected_company_ids_json">[]</column>
  <column name="selected_person_ids_json">[]</column>
  <column name="recipient_distribution_json">[{"personId":"person-uuid","selected":true,"role":"to"}]</column>
  <column name="is_default">0</column>
  <column name="default_workflows_json">["status-report"]</column>
  <column name="settings_version">1</column>
 </row>
</table>

Column	Meaning
`id`	Unique ID of the saved audience group.
`project_id`	Owning project ID. Its `lookupvalue` is the project number, which import uses to find the project in the destination database.
`workflow`	`project` for current groups shared by the project's report and meeting workflows.
`audience_name`	Name shown when choosing a saved group.
`people_source`, `company_filter`	Saved audience rule; current groups use `project-team` and `all`.
`selected_company_ids_json`, `selected_person_ids_json`	JSON arrays of IDs used by audience rules; normally `[]` for current groups.
`recipient_distribution_json`	JSON array of recipient choices. Each entry has a `personId`, a Boolean `selected`, and a `role` of `to`, `cc`, or `bcc`.
`is_default`	Legacy default flag; current defaults are recorded in `default_workflows_json`.
`default_workflows_json`	JSON array of workflows for which this group is the default, such as `status-report`, `tracker-items-report`, `meeting-notes-report`, `send-meeting-notes`, or `schedule-meeting`.
`settings_version`	Version of the saved audience settings; current groups use `1`.

The JSON fields contain database IDs. When moving a project between databases, import resolves the project_id by project number, but IDs inside those JSON fields are not translated. Check recipient choices after importing into a different database.

The XML document follows a parent child heiarchy that corresponds to the record relationships found in your database. If a <row> has several related records it will contain one or more <table> nodes as children. Data in the XML export is often repeated to make plugin writing easier. Below is a table that describes the different node and attribute types.

Element	Type	Description	Required For Import
<projectnotes>	Document Root Node		Yes
filepath	Attribute	The database the XML was exported from	No
export_date	Attribute	The date the data was exported	No
delete	Attribute	When delete is set to true the record will be deleted. This method does not account for related records and could leave records abandonded in the database if not used correctly.
filter_field_#	Attribute	The field filtered to limit the data exported. This used when calling get_data to find results. Multiple field value pairs can be used as long as # matches.	No
filter_value_#	Attribute	The value used to filter the data exported This used when calling get_data to find results. Multiple field value pairs can be used as long as # matches.
project_manager_id	Attribute	The database record id of the Project Manager specified in the Preferences	No
managing_company_id	Attribute	The database record id of the Managing Company specified in the Preferences	No
managing_company_name	Attribute	The name of the Project Manager specified in the Preferences	No
managing_manager_name	Attribute	The name of the Managing Company specified in the Preferences	No
<row>	Document Node	The database row exported or imported	Yes
id	Attribute	Only used on import to target a specific existing record for update or delete. When specified, Project Notes uses the id to locate the record by its primary key. Not present in exports — the record ID is exported as the first `<column>` element instead. It is important to realize using an id from one database in another can cause errors since ids are globally unique per-database.	No
<column>	Document Node	The column node to be imported. The value may be the column value, or the lookupvalue may be provided to specify the import lookup the corresponding record id. Typically corresponding record ids are not given as values.	Yes
name	Attribute	The name of the column to be imported	Yes
lookupvalue	Attribute	In many cases a record relates to another record. For example Contacts and Companies, are related by their record id. To relate records on import, this value should contain the corresponding name. For example: The project_id field should have this value set to the project_number. The client_id field should have this value set to the company name. The people_id should have this field set to the contact name.	Yes

Suggest an edit on GitLab