Upload Work Items

Modified on Wed, Sep 4 at 6:59 PM

Use the Work Item Upload feature to upload large batches of work items.

Work items are created from forms (+ Create). Forms are created in the App Designer. In order to upload many work items at once, they must match an existing form (each field in the work item must match a field in the form). To ensure the work items match an existing form:

Download the template (form). The system creates a CSV template file from the form. The fields in the form are the column headings in the CSV template file
Put your work item data into the CSV template file
Upload the work item data (in the CSV template file)

Download Template (CSV File)

Templates are your company's forms. The system creates a CSV template file from the form. The fields in the form are the column headings in the CSV template file

On the top menu bar, click System Management ( ) > Administration tab > Work Management > Upload Work Items
On the Work Item Upload Summary page, in the upper-right corner, click Download Template
In the Download Template File window, choose the template (templates are your company's forms).
Click Download
Determine where to save the template file on your device. Template files are in Comma Separated Value (CSV) format and can be opened in Microsoft Excel or any text editor

Add Work Items to Template CSV File

Most of the time, you create work items by clicking Create (+) on the top navigation bar. However, to create many items at once, download a template file, fill the file with data for your work items, then upload the file.

The template is a Comma Separated Value (CSV) file the system creates from the form you chose. The field names from the form are the column headings in the CSV file.

Use Microsoft Excel to add your item data to the template file.

Dates. Microsoft Excel converts dates to a month/date/year format (mm/dd/yyyy). The system requires dates to be in year/month/date format (yyyy-mm-dd). To avoid errors, format date columns in Excel to be Text fields before putting in data.

Field Types. The Upload Work Items feature does not support these fields. Templates do not contain these fields (even if the form the template is based on does have them) so data cannot be uploaded into them. If you need to create items containing these fields, you must manually add them after using the template to upload all the other fields. They are valid fields when manually creating and updating items and when using the GetWorkItems API.

Calculation
Data List
Multiple Components (if using a Component, you cannot configure it to allow multiple Components)

Use IDs to Update Existing Items

To update existing items, add a column for one of these IDs so the system knows which existing item to update with new data:

ExternalID: An ID from a non-Irth system

ItemID: The ID used by the system and visible in the URL of an item. The ItemID is available via the GetWorkItems API on the Integration Configuration page. This ItemID is not the Item ID visible on many pages in the system, such as the Item Details page.

Upload Work Items (Template CSV File)

On the top menu bar, click System Management ( ) > Administration tab > Work Management > Upload Work Items
On the Work Item Upload Summary page, in the upper-right corner, click Upload Work Items

In the Upload Work Items window, choose the options and file to upload. Files must be either Microsoft Excel or Comma Separated Value (CSV) files

Option	Description
Ignore Required Fields on Form (form)	Checked: If required fields are empty, the system will accept the file in most cases. Exception: The Title field must contain data even if this box is checked Unchecked: If required fields are empty, they will be noted in the report in the Errors column. See Errors
Name	The unique name of the upload. Use this field to identify the upload. For example, enter the date or a note. Follow your company's method
Work Item Type	Work item types are your company's forms. The work item data you are uploading must match a form (the column headings in the file of work item data you are uploading must match the fields in the work item type (form)
Update Existing Items	Checked: The system tries to match the items in the file you upload to existing items based on ItemID or ExternalID: If they match, the uploaded items replace/update the existing items If they don't match, the Error column says "Yes" and resulting Excel file has an error message saying items were not found. See Errors Unchecked: The system creates new work items

To locate the file, click Browse

Click Upload. The system uploads the file and uses the data in it to create items
The system confirms the upload succeeded. The upload appears on the Work Item Upload Summary page with "Pending" in the Status column

Errors

The system generates an error report for the data it cannot process. Errors can be caused by:

ItemIDs don't match
Missing required fields
Invalid data
Wrong work item type (mismatch between the item data in the file you uploaded and work item type)

Correct Errors

In the Errors column, click Yes. Result: A CSV file downloads containing the items with descriptions of the errors
Open the CSV file, correct the errors, and upload again. You do not need to upload items that have already been uploaded without error