How to use runFromCsv

Owned by Bob Swift
Last updated: Feb 07, 2020 by Michael KuhlVersion comment

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. 

Action
jira --action runFromCsv --common "--action setFieldValue --field custom1" --file cf.csv
cf.csv
Issue, Values
ZCLI-1, xxxx
ZCLI-2, yyyy
Output
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.

Action
jira --action runFromCsv --common "--action setFieldValue --field custom1" --file cf.csv --propertyFile import.properties
cf.csv
Key, "My custom1 value"
ZCLI-1, xxxx
ZCLI-2, yyyy
import.properties
# 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
Output
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

Property File
# Use ; as the CSV delimiter - must be a single character
delimiter = ;