feat: Support custom fields on issue create

[ankitpokhrel]

This PR adds initial support for custom fields on the issue creation. Relates to #222. Fixes #340.

Jira supports a wide variety of datatypes when creating a custom field. Out of all formats mentioned in the Jira doc, the implementation right now doesn't support Cascading select custom field, Single-user picker custom field and Multi-user picker custom field. Support for these missing types will be added based on the request and the usecase.

Implementation Details

Since we are already using the createmeta endpoint to save metadata during jira init process, this step is modified to save custom field details. The initialization process will now add a new section issue.fields.custom to save required details about configured custom fields.

Next, a new flag --custom is added on create command that accepts a key-value pair. The key is derived from the name you see in the configuration. This is the same name that you see in the UI making it easy to guess. Dash/hyphen (-) separated lowercase name is used as a key. The value depends on the datatype of the field. For some datatypes like string, datetime, date, option, the value is a plain string (eg: --custom note="An example note"). For array types, its a comma separated value (eg: --custom platform=iOS,Android).

Example

Given some custom fields as below:

Custom Field	Field Type	Comment
Due Date	Datetime	ISO 8601 ('YYYY-MM-DDThh:mm:ss.sTZD') format
Note	Paragraph	A single or multiline text input
Platform	Checkbox	Array of strings
Quarter	Radio button	Single value string data
Tags	Labels	Array of strings

You can use --custom flag to pass data for custom fields

$ jira issue create -tStory --custom story-points=3 --custom due-date="2022-03-10T14:39:00.000+1100" \
 --custom note="A custom note" --custom platform=Windows,Linux --custom quarter=Q3 --custom tags=p1,q3,y2022

# Or, alternatively

$ jira issue create -tStory --custom=story-points=3 --custom=due-date="2022-03-10T14:39:00.000+1100" \
 --custom=note="A custom note" --custom=platform=Windows,Linux --custom=quarter=Q3 --custom=tags=p1,q3,y2022

The example command above creates a story with defined custom fields of different types as seen in the screenshot below.

Caveats

The Jira API returns invalid types for some locked custom fields. For instance, for the sprint field the returned datatype is an array of strings or JSON depending on the Jira version used. However, that is not true since the create API expects a single numeric value for a sprint field.

In such cases, the config needs to be modified manually to make the field work.

# Details returned by the Jira API for sprint field
- name: Sprint
  key: customfield_10020
  schema:
     datatype: array
     items: json

# Manual change needed to make it work
- name: Sprint
  key: customfield_10020
  schema:
     datatype: number

Testing

To try out this change, you can either build the app locally or install it using the following command.

go install github.com/ankitpokhrel/jira-cli/cmd/jira@request-222

Note that you will have to regenerate the config with jira init.

[realtime-neil]

@ankitpokhrel how does one supplement an extant configuration with custom fields; i.e., how do I do this without re-invoking jira init?

[ankitpokhrel]

@realtime-neil You can generate config in a new location using XDG_CONFIG_HOME env. For example the command below will generate a new config in current working directory.

 XDG_CONFIG_HOME=. jira init

You can then keep using the same env for subsequent commands or you can use -c/--config option to pass new config location.

$ XDG_CONFIG_HOME=. jira issue create

// or

$ jira issue create -c </path/to/new/.jira/.config.yml>

If you don't want to run jira init, then the config file needs to be prepared manually. issue.fields.custom is the new section added to the config.

issue:
  fields:
    custom:
    - name: Epic Link
      key: customfield_10014
      schema:
        datatype: any
    - name: Sprint
      key: customfield_10020
      schema:
        datatype: number

[realtime-neil]

@ankitpokhrel you're suggesting that, in addition to a given existing configuration, I use jira init to create a completely new configuration in a different location? And then manually resolve the diff between the pair?

[ankitpokhrel]

you're suggesting that, in addition to a given existing configuration, I use jira init to create a completely new configuration in a different location?

Yes, if you want to try out this change without tampering your current config. And if this works, you can simply run jira init and override actual config.

[m4dc4p]

create worked with the custom fields we use (two option fields, and two string fields). I would love to see this expanded to edit too, but fantastic work so far. Thank you!

[ankitpokhrel]

@m4dc4p Thank you for testing! Yes, it will be expanded to edit once this is merged and stable.

[realtime-neil]

@ankitpokhrel is there any facility for querying available custom fields?

[ankitpokhrel]

@realtime-neil From the tool, no. If you need this info to test something then you can use the following curl commands.

# Get all fields
curl --request GET \
--url 'https://<server-url>/rest/api/2/field' \
--user "<user>:$JIRA_API_TOKEN"

# Get fields available on create
curl --request GET \
  --url 'https://<server-url>/rest/api/2/issue/createmeta?projectKeys=<project_key>&expand=projects.issuetypes.fields' \
  --user "<user>:$JIRA_API_TOKEN"

[zsolt-p]

I'm really excited about this, thanks! But unfortunately, it doesn't seem to work for me. I get the new custom field in my config file as an option datatype after rerunning jira init, and I create the issue like this:

jira issue create --custom CustomFieldName=value
# or with quotes
jira issue create --custom CustomFieldName="value"

The issue is created with no error, however the custom field does not get added. I tried changing the datatype to string and any, but none worked.

Here's the corresponding bit of my config file

issue:
  fields:
    custom:
    - name: CustomFieldName
      key: customfield_10082
      schema:
        datatype: option

[ankitpokhrel]

Hi @zsolt-p, the config looks ok to me. I think the problem is with case-sensitive comparison I am doing in one place.

The key is derived from the name you see in the configuration and dash/hyphen (-) separated lowercase name is used as a key. So, for example if your custom field is called DeploymentNote, you should pass --custom deploymentnote="value" (all lowercase) and if your custom field is called Due Date, you should pass --custom due-date="2022-01-01" (lowercase separated with hyphen).

Could you please check and confirm if that works for you? I will make this comparison flexible if you can confirm.

[zsolt-p]

@ankitpokhrel confirming it works

You're right, our custom field has an uppercase char, lowercasing it in the command makes it work, thank you

i.e.

jira create issue --custom customfieldname="value"

for a config file that looks like this

issue:
  fields:
    custom:
    - name: CustomFieldName
      key: customfield_10082
      schema:
        datatype: option

[vballestra-latch]

Really cool stuff here! Thanks.

I would like to suggest two additional features:

• new command to inspect the meta (like enumerating the custom fields for a given issuetype on a project). So that one knows exactly how a custom field is named
• an option to update the config with existing credentials rather than creating it again from scratch. This can be useful whenever new projects are created or issue types are updated on the server

And obviously and interactive way of adding the fields would be awesome indeed.

I'll checkout the branch to help testing!

[ankitpokhrel]

@vballestra-latch Thank you for the feedback!

Regarding your suggestions, there is a plan to work on a config command (similar to git config) to manage the configurations required for the CLI. However, this may not happen anytime soon because of other priorities.

I haven't given much thought on the command to inspect meta, but that can be included if needed. Let's first see how the users will use this feature and the issues they will run into. We can then decide on the required features.