This page describes Data Loader and includes the following sections:
- Main Features
- Field Identification
- Updating Data to Clarizen
- WBS Load
- Adding Work items to Existing Project
- Create From Template
- Undo Load
- API Support
Data Loader enables you to insert or update Clarizen item types or fields by uploading XLS, XLSX or CSV files.
The data loader utilizes API calls for its functionality and therefor adheres to the API governance and limitations defined by Clarizen
The first Excel file worksheet is imported by the Data Loader.
This file should contain the field names in the header row, and the data to be inserted or updated located in the worksheet’s data
cells. The update is a two-phase process; the first phase is to upload and verify the data with some pre-load validations.
Even once this phase has completed, data is still not inserted into Clarizen yet!
It is only upon completion of the second phase that and receives feedback from Clarizen with the indicating that procedure has
been successful. Once done, an email is generated and sent to the User who performed the load procedure,
and a task with the load details opens on a default upload project within the organization.
The task will typically come with a few attachment documents,
the original load file with the data, an Errors/Messages file from the load, and an Undo file to enable you to undo the transaction.
It is strongly recommended that the User performing the upload procedure is an Admin User, Super User and Financial User,
in order to avoid 'update blocks' due to insufficient authorization privileges.
- Select the item type you wish to upload from the Item Type list
- Provide an optional name for the loading process
- Select the file you wish to upload
- Click Upload
Figure 1: Set Item Type and Select File
Figure 2: Updating Clarizen
Figure 3: Update Complete
This section describes the main concept features.
- Ability to receive a CSV file with the item type description.
The file includes all the item type fields (including the item type properties) and supported relations.
- To receive the described file, select the relevant item type, click the Advance link and then the Entity Description link
Figure 4: Advanced Options
- The field names specified in the Header row may contain the API name or the field screen name
- Custom fields (of all types) are supported out of the box just like the Clarizen system fields
- The special type field formats (such as Duration and Money) are identical to those within Clarizen
- Reference to item fields (Users excluded) are matched by the ExternalId, Sysid or by name (as last resort)
- Reference to User fields are matched by the ExternalId, email address, Display name and User name
- Reference to items in link fields (Resources, Reviewers, Customers etc.)
operates with the same logic as regular reference to item fields with a separator of comma between the objects
(for example, user.name1,user.name2,email@example.com)
- Please note that in order to support adding reference to item in a Link type field,
You are required to add the prefix of 'Link:' before the column name in the header row
- The list of available links for an item type can be found in the describe file
Figure 5: Field Identification
Inserting Data to Clarizen:
- Ability to insert new records into Clarizen-specific tables (item types)
- To insert new rows, select the relevant item, select the file to upload, and then click Upload and then click Update Clarizen
- Ability to update existing records in Clarizen-specific tables (item types) by the item type identifier
- It is up to you to choose the item type identifier. All you have to do is to add 'PK:' to the relevant column(s).
The values in these columns will be added into the "where condition" that finds the relevant item.
Figure 6: Item Type
- To update existing rows, select the relevant Item type, select file to upload, click Upload and then click Update Clarizen
You can insert and update records in the same transaction by specifying the item type identifier column.
If the identifier exists in the row, an update is performed, and if the identifier is blank, an insertion is performed.
- You can load an entire project into Clarizen, including sub-projects and nested work items
- To load an WBS file, select the work item item type and load a file containing 'Level1:Name', 'Level2:Name'…'LevelN:Name'
in the load file Header row
- In order to load a WBS, you have to add a column named EntityType and specify the relevant work items type
(project, milestone or task)
Figure 7: WBS Load
- In order to add work items to an existing project you have to run a designated custom action on the specific project
- All work items loaded in this load are linked to the selected project
- You can specify a list of project and/or milestones that you want to create from a template.
In order to support this functionality, you have to add a column with the value ‘FromTemplate’ in the Header row
- When creating a project from a template, the values identify the data cells is the template name in Clarizen
(for example, My Template Name)
Figure 8: Create Project From Template
- When creating a milestone from a template, the values identify the data cells is the template name in Clarizen, comma, and the milestone parent name (for example, My Template Name,Parent name)
Figure 9: Create Milestone From Template
- At any time, you can decide to undo the entire load and delete all the records inserted in a specific load batch
- The Undo feature works only on inserted records and not on updated ones
- In order to undo a specific load:
- Click the Advance link.
- Click the Undo Load link.
- Search for the relevant load transaction.
- Click the Undo button for the specific load, and wait for the record to be deleted.
Figure 10: Undo Load
- You can also activate this load process by invoking a SOAP web service
- The interface function format is:
- Public UpdateErrorNative Load(string sessionId, string fileName, string entityType, byte fileContent, bool validateOnly)
- To activate this functionality, please contact your Clarizen representative
Examples are available for download by clicking the link below.