Server controlled, user-friendly issue identifiers

[ykulbak]

What is proposed

When issues are returned from a BCF server the payload may include a server controlled, user friendly and project-unique issue identifier. BCF clients may choose to present the identifier in their UI allowing the user to visually locate the issue in the server UI.

Note: two issues on the same project will never have the same identifier. Issues on different projects may have the same identifier.

Why?

Most issue servers already provide a mandatory, server controlled, project-unique and user friendly issue identifiers. In most cases the identifier is a running number, starting at 1. In fact, I couldn't locate a single server which doesn't have a user-friendly issue ID. These identifiers, when combined with the project ID provide a unique way to identify the issue on that server.

It is a lot easier for users to converse about "Issue 314" or "Issue 283". rather than Issue with GUID "a8e997f5" or Issue with GUID "b3513ee1".

Also in BCF-XML?

Ideally this can also be provided in BCF-XML. The problem with that is that it adds complexity to explain that the server will ignore this field when importing the issue and may export the issue with a completely different value later.

Mandatory?

Ideally yes. Servers can default to a unique prefix of the issue guid if they don't support this feature already.

[Amoki]

The index field on a topic is meant to do this. We use it like that at BIMData.io at least.

[gliderguy]

There is a risk that this index field could be used for two different purposes.
I see this index field as alterable by the system based on user preference.

Does the documentation need to be clearer?

In the BCF-XML markup it has:

<!-- ISG Jira issue BCF-8 Add a way save order the topics -->
<xs:element name="Index" type="xs:int" minOccurs="0"/>

This implies to me that the index number can be changed depending on how the user wants the topics ordered. An example is in a Jira backlog, the issues can be ordered/prioritized independently of the jira issue number sequence.

Would this not be the same for the BCF-API? The description says:

index | index of a topic

It is not clear if this index field is for adjusting the ordering of topics or an immutable number within the system that identifies an issue to allow the user to easily cross reference an issue in another system to the BCF server.

Another point on field type
In the BCF-XML this field is an int. An issue id/number may not always be a number although from the examples I have seen it is. If the issue is always retrieved in the context of the project/project id then maybe the issue number can always be an int.

[ykulbak]

I agree with @gliderguy. I believe the index field serves as an ordering hint. It can be provided by the client (not server controlled) and it doesn't have to be unique.

[Amoki]

I think you're right. There is not enough constraint on the index field to be used like the proposition. Our implementation is quite similar to your description with some difference:
The issue identifier is unique by project, the user can ask for it (importing/exporting from other BCF tools keep issue IDs) but if there is a conflict, the server overrides the value.
A number seems better than a string to be: easier to generate server-side, can still be shown as "Issue #258" in apps, and less conflict-prone (case, non-latin chars, spaces, etc).