Importing and Exporting Tasks
Importing Tasks
OnePlace provides the ability to imports tasks into your workplaces from a comma-separated value file (CSV). You can create new tasks as well as update existing tasks. There are two places within OnePlace where you can import tasks. The first is in the "All Tasks" mode using the "Import Tasks" button (shown below). The second is on the Tasks tab within a workplace, which has an "Import Tasks" button as well.
Import Tasks Dialog
Importing tasks is easy. Just click the "Import Tasks" button, and the dialog below will pop up. Browse your hard drive for a CSV file containing tasks formatted accordingly (see the format below), and then click the Import button. If the tasks import successfully, a message will flash on the screen briefly telling you this. Otherwise an Errors box will appear on the dialog listing the errors that were encountered during the import. Each error will tell you the row/line number in the CSV file that the error occurred on. All tasks must import successfully in order for any changes to be saved to the database. If you encounter errors in your file, simply correct those errors, and try re-importing the file.
Import File Format
The first row/line in the import file defines the task fields that the file contains. These fields must be separated by commas. Fields can be ordered however you like, and any extra fields (i.e. those not recognized by OnePlace) are simply ignored.
The remainder of the rows/lines in the file contain the task values, which are also separated by commas. If a value contains a comma, it must be surrounded with double quotes in order for that row to process correctly. Blank rows are ignored.
Date values can be either an actual date in the format m-d-y, m/d/y or m/d (current year is assumed for last format), or a relative date of today, tomorrow, yesterday or +N, where N is a whole number. Here are some examples:
- 12/12/2009
- 12-12-2009
- 12/12
- today
- tomorrow
- +3
Note: You must save your CSV file with the Unicode (UTF-8) character/text encoding in order for OnePlace to read certain characters correctly. The application you use to create your file should allow you to choose the character/text encoding when you save/export the CSV file.
The table below describes the possible fields that you can include in your import file. Required fields are marked with a red asterisk (*). All other fields are optional. Note that field names are not case sensitive, meaning that Workplace, WORKPLACE and workplace are all treated the same.
| Fields | Possible Values |
|---|---|
| assigned_to | The first name, full name or email address of a member of the specified workplace to assign the task to. If two people in the workplace have the same name, specifying this name will result in a validation error. Use the person's email address instead. |
| billable | Species whether this task is billable or not. Valid values are: Yes/No, True/False, 1/0 (not case sensitive) |
| context | The full path for a context (including parent contexts), where contexts are separated by / or \. For example Home\Inside\Desk and Outside/Garden. This field is ignored unless the task is assigned to the person who is doing the importing (i.e. the "current" user). |
| custom1 | Any value |
| custom2 | Any value |
| custom3 | Any value |
| deadline | The date the task is due/must be done by. A date string (see above for supported formats) |
| description | The description of the task (any value) |
| estimated_effort | Estimated effort in hours. Specify minutes as a fraction of an hour. For example, 4 hours and 15 minutes is specified as 4.25. |
| *id | The identifier (ID) of the task. This field is only required when updating existing tasks. If not specified or left blank, a new task will be created. |
| invoiced | Species whether this task has been invoiced or not. Valid values are: Yes/No, True/False, 1/0 (not case sensitive) |
| invoiced_amount | A decimal number representing the amount a billable task has been invoiced for |
| invoiced_on | The date a task was invoiced on. A date string (see above for supported formats) |
| priority | Low, Normal, High (not case sensitive) |
| project, project_path |
This can be either the title or the identifier (ID) of a project within the specified workplace. When specifying the project by title, a full or partial (begins with) title can be used. When specifying the title of a sub-project, you must include the full or partial titles of the parent projects separated by / or \. If two or more projects match the title you provide, this will result in a validation error. Try again with a more specific title. |
| permissions | Full, Limited, Portal (not case sensitive) |
| quoted_amount | A decimal number representing the amount a billable task is quoted for |
| scheduled_on | A date string for when the task should be scheduled (see above for supported formats). This field is ignored when the person doing the importing (i.e. the "current user") does not have permission to schedule work for the person the task is assigned to. |
| status | Draft, Planned, In Progress, Waiting for, Completed (not case sensitive) |
| tags | A list of tags. Separate multiple tags using a | character. You can also separate multiple tags using a comma, but you must surround the tags with double quotes in order for this to work correctly. |
| *title | The title of the task (any value) |
| track_time | Yes, No (not case sensitive) |
| unplanned | Species whether this task was planned for or not (unplanned). Valid values are: Yes/No, True/False, 1/0 (not case sensitive) |
| *workplace | The name or identifier (ID) of a workplace. Either this value or the 'workplace_id' value described below is required to be specified, but both are not required. |
| *workplace_id | The identifier (ID) of a workplace. Either this value or the 'workplace' value described above is required to be specified, but both are not required. |
Import File Example
id,workplace,project,title,estimated_effort,deadline
,Private Workplace,Bathroom Remodel,Tear out old tub,4.0,7-10-2010
125,Family,,Take fluffy to the groomers,2.0,tomorrow
Exporting Tasks
OnePlace allows you to export tasks to a comma-separated value file (CSV). The format of this file is nearly identical to the format used when importing tasks from a CSV file. You can do this for all or a subset of the tasks that you have visibility to (via the workplaces you belong to), or for the tasks in your team account if you are an administrator of that account. One use for this feature is to extract task information from OnePlace so that you can manipulate it in some another program such as Microsoft Excel.
There are two places within OnePlace that you can export tasks. The first is within the "All Tasks" mode. The Export button in the All Tasks toolbar is called out in the screen shot below:
The second place is within your Personal Account Settings or Team Account Settings (if you are an administrator of your team account). You access your account settings via the Settings menu in the upper right hand corner of the page. The "Export Tasks" link in the "Actions" panel for your account settings is called out in the screen shot below:
OnePlace uses a wizard-style dialog for exporting tasks, which walks you through the steps for setting up the necessary filters used to retrieve the set of tasks you are after. Previous/Next buttons at the bottom of the dialog can be used to walk forwards and backwards through the screens. Note that you won't be allowed to go to the next screen until you've properly filled out the current screen.
Choose a Time Frame
This screen allows you to define a time frame for the tasks that are retrieved. You can either choose "All", which effectively means don't apply a time frame, or you can choose a specific time frame. This screen lets you constrain the tasks that are exported by when something happened, such as "export tasks that were worked on between December 1st and December 31st".
- Start Date — The starting date for the time frame
- End Date — The ending date for the time frame. This must be on or after the start date.
- Date Field — The date field to filter on. For example, "Completed on" or "Worked on". "Worked on" is when you applied time to a task. So, you have to be using time tracking for a task for this to have meaning.
For tasks that track time, you can define how tasks should be exported to the file:
- Export one task for all effort applied to the task — Each task is written to the export file once, and all time that has been applied to the task will be totaled on the task.
- Export one task for each date effort was applied to the task — A task is written to the export file for each date that effort was applied to the task. The total time applied on that date will be listed on the task record in the export file. So, if effort was applied five different times for a task on two different days, two records will be written to the export file for that task.
- Export one task for each time effort was applied to the task — A task is written to the export file for each time that effort was applied to the task. So, if effort was applied five different times for a task, five records will be written to the export file for that task.
If the "Restrict time entries to specified time frame" option is checked, none of the time applied to the matching tasks which falls outside the specified time frame will be included in the export. This will impact the actual and remaining efforts for the exported tasks.
The "Export By" choice determines if tasks will be exported by workplace or by project. The choice you make here determines which screen appears next.
Export By Workplace
This screen is shown if you choose the "Export By Workplace" option on the Time frame screen. It allows you to define which workplaces you want to export tasks from. You can either choose all workplaces, or choose a subset of the workplaces in the account.
- Manager — This is a list of the users who manage workplaces in this account. Choosing a specific manager will change the workplaces shown in the list below to only the workplaces managed by that user. For more information on setting the workplace's manager, click here.
- Workplaces — This list contains either all the workplaces in the account, or, the workplaces managed by the user selected in the Manager drop down.
Export By Project
This screen is shown if you choose the "Export By Project" option on the Time frame screen. It allows you to define which projects you want to export tasks from. You can either choose all projects, or choose a subset of the projects in the account.
- Projects — This list contains all top level projects in the account, sorted by the workplace they belong to.
- Include tasks in sub-projects — If checked, tasks in sub-projects under the top-level projects you selected will also be included in the export.
Choose the Users
This screen is used when you want to filter the tasks by one or more actions performed by one or more users. For example, you may want to "export tasks created by either Mary Jones or Bill Brown".
- Users — This list contains all users who belong to workplaces owned by this account. When multiple users are selected, they are combined in the resulting filter using OR. For example, if Bob Brown and Bill Black are selected, the resulting filter would read: "Export tasks that Bob Brown or Bill Black ?", where ? is one of the users fields such as completed, assigned, etc.
- Fields — The user field to filter on. For example, "Created by" or "Completed by".
- Combine fields using AND or OR — Determines how to combine the user fields when two or more fields are selected. Suppose Tad Green and Tilly Smith are selected as the users, and "Assigned by" and "Completed by" are the selected user fields. If you choose the AND option, the resulting filter would read: "Export tasks that Tad Green or Tilly Smith assigned, AND Tad Green or Tilly Smith completed." If you choose the OR option, the resulting filter would read: "Export tasks that Tad Green or Tilly Smith assigned, OR Tad Green or Tilly Smith completed."
Choose the Task Statuses
This screen is used when you want to filter by one or more particular task statuses. For example, you may want to "include tasks that are in progress or waiting for". There are also a couple of other options on this screen you can choose (disposition and formatting) for controlling how the tasks are exported.
Export Summary
Once you have made your filter selections on the screens described previously, and are ready to export your tasks, OnePlace will show you a summary of what you selected. It's a good idea to review the summary before exporting your tasks to make sure you've made the correct selections. You can click the Previous button to move back to any of the previous screenss to change your selections at any time.
Click the Export button at the bottom of the screen to export your tasks. Once the export completes, you will see the following screen:
Note that the file that was created will be kept for one hour before being deleted. Click the Download button to download the file to your computer.