How to use runFromCsv
On this page
Related Information
Description
This describes how to use runFromCsv for various automation tasks. Examples are used to demonstrate use cases. This assumes familiarity with running JCLI actions, JCLI is installed, and the script file has been modified for your installation - see Installation and Use.
The basics of runFromCsv are similar to the other run based actions, each csv line of the file is treated as parameters for a single action. Note that a csv line can span multiple source lines using the appropriate csv quoting rules (see The Comma Separated Value (CSV) File Format). Either the header line must have the correct parameters names or a properties file needs to be provided to map column names to parameters names.
Test
Best to test more complex or larger actions on a test instance.
Also, you can use --simulate to help with constructing and testing the various run actions.
Continue
Consider using --continue to continue processing on error for the various run actions. Otherwise, the processing will stop on the first action that fails.
Omitting columns for a specific row
Use @omit@ for a specific entry to omit that command line parameter from being generated for the row it is on. This is helpful when a common parameter should NOT be used at all for a specific line, but might be needed for some other line.
Type, Something, Something else Bug, @omit@, @omit@
Example - updating custom fields
This example will update a single custom field named *custom1* for each of the issues identified in the csv. Note the Issue and Values header line is important and maps the columns to the issue and values parameters of the setFieldValue action.
jira --action runFromCsv --common "--action setFieldValue --field custom1" --file cf.csv
Issue, Values ZCLI-1, xxxx ZCLI-2, yyyy
Run: --action setFieldValue --field custom1 --values "xxxx" --issue "ZCLI-1" Issue ZCLI-1 updated. Run: --action setFieldValue --field custom1 --values "yyyy" --issue "ZCLI-2" Issue ZCLI-2 updated. Run completed successfully. 2 actions were successful from file: /development/attachments/cli/files/cf.csv
Example - using properties to map names
When the CSV file has column names that differ from what the JCLI needs, you will need to map the names to the correct parameters.
jira --action runFromCsv --common "--action setFieldValue --field custom1" --file cf.csv --propertyFile import.properties
Key, "My custom1 value" ZCLI-1, xxxx ZCLI-2, yyyy
# Map field headings to parameters understood by the JIRA CLI # - key values (left hand side) must not contain blanks, blanks can be escaped (with \) if needed # - the first character of field names will be automatically lowercased (except for custom fields) # - field headings with embedded blanks are ignored unless they are mapped # - field heading that should be ignored should be mapped to blank # - custom fields can either be specified by name, id (like customfield_10120), or id (like 10120) # - value mappings can also be done, they are specific to the (mapped) field name field.Key = issue field.My\ custom1\ value = values
Run: --action setFieldValue --field custom1 --values "xxxx" --issue "ZCLI-1" Issue ZCLI-1 updated. Run: --action setFieldValue --field custom1 --values "yyyy" --issue "ZCLI-2" Issue ZCLI-2 updated. Run completed successfully. 2 actions were successful from file: /development/attachments/cli/files/cf.csv
Example - using properties to ignore columns
Project, Type, Summary, Description, Affects Versions, Notes ZCLI, bug, Bug summary, Bug description, V1, this is a note ZCLI, improvement, Improvement summary, Improvement description, V2
# Ignore the description field field.Description = # Ignore the notes field as it would be considered invalid field.notes = # Column names with blanks are automatically ignored. They need to be mapped to a valid parameter to be used. field.Affects\ Versions = affectsVersions
Example - when a CSV file is using a different delimiter
# Use ; as the CSV delimiter - must be a single character delimiter = ;