Upload Work Items

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:

  1. 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
  2. Put your work item data into the CSV template file
  3. Upload the work item data (in the CSV template 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

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

  3. In the Download Template File window, choose the template (templates are your company's forms).

  4. Click Download
  5. 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

 

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.

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.

 

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

  3. 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

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

 

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

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