Vscode-extension-for-zowe: Change Wording in Add Profile Wizard

[VitGottwald]

Is your feature request related to a problem? Please describe.

The last question in the dialogue for creating z/OSMF profiles about _Reject Unauthorised Connections_ is confusing

Describe the solution you'd like

Change the formulation from "Reject Unauthorised Connections" to "Allow Self Signed Certificates", with the options "yes" and "no".

Additional context

I believe that a question about _self signed certificates_ will be more understandable to a broader audience compared to _reject unauthorised_ which is specific to a particular programming environment (nodejs).

[dkelosky]

This is something that's been debated since we released Zowe CLI 😄.

We deliberately chose the wording to align with Node.js. Other packages, like request abstracted this behavior to a parameter insecure. However, we wanted to be able to point users directly to the Node.js documentation for a description of the behavior.

Two other points:

• we would want consistent terms between CLI & Zowe Explorer
• self-signed certificates are a subset of errors for which rejectUnauthorized bypasses

I understand the confusion, but I hope it helps explain why we chose what we did.

[dkelosky]

related to #267

[VitGottwald]

Thank you for the background @dkelosky . It certainly helps to understand the current situation for me!

The question is whether what we have in the dialogs helps our users to understand it. Given the fact that you had to give me this background, I would say it does not.

So I would argue that a slightly imprecise message that connects with our users and conveys the gist of the issue is better than a technically accurate one that is cryptic. We can put the technical details into the docs.

[dkelosky]

NP on the background 😄.

If we use slightly imprecise messaging and need to explain the technical details in a separate doc, I think we're in a worse place than we are now. rejectUnauthorized is a known, searchable term which brings up hits for Node.js. Searching for our own language-abstraction can lead to unrelated documentation.

It might also be the case that users only need to provide NODE_EXTRA_CA_CERTS instead of rejectUnauthorized.

Our larger goal is to eliminate the need for most users to answer any of these questions in the first place (using project config).

We need to be in sync with Zowe CLI. Since, the original issue is stale and a large user base manages to get around this, I suspect this is a low priority item to pursue.

[tucker01]

It is probably important to understand, that in the early days of Zowe and the CLI, we made a conscious decision to avoid translation in terminology.

As a simple example, take something like "data set" vs "file". While both may be appropriate in casual conversation, the proper term in an MVS context would be "data set".

Translating terminology, with the hope that its more understandable to a user is a mixed bag, on one hand, based on their experiences, some users may understand immediately, on other hand, some users are left scratching their heads.

However, when left scratching your head... the natural course of action is to google. If we translated terminology, googling is much less effective and could be misleading. And as @dkelosky mentioned, there may be subtle implications to something like rejectUnauthorized that translation would obscure.

There is more to the rationale, but hopefully this makes sense.

[VitGottwald]

Thank you @dkelosky and @tucker01 for the extended explanation. For someone who has not been there since beginning it is always great learn about the reasoning that led to decisions.

It might also be the case that users only need to provide NODE_EXTRA_CA_CERTS instead of rejectUnauthorized

Do we have that ability in ZOWE Explorer?

It is probably important to understand, that in the early days of Zowe and the CLI, we made a conscious decision to avoid translation in terminology. ...

If I remember correctly the feedback from users is that this question we have in ZE is confusing, @jelaplan, please correct me if I am wrong. I agree we should not be translating terminology like data sets. I also agree that and the profile field name should be called rejectUnauthorized.

But if we are told the question in our dialogues is confusing and we can easily disambiguate it, should we not fix that?

[MikeBauerCA]

Our larger goal is to eliminate the need for most users to answer any of these questions in the first place (using project config).

I suspect some users would still be confused by "Allow Self Signed Certificates"

[VitGottwald]

Our larger goal is to eliminate the need for most users to answer any of these questions in the first place (using project config).

If there is less need for asking the users, all the better. However, this issue is formulated in the context of the current dialogues. If we ever decide to get rid of them altogether is a separate discussion.

I suspect some users would still be confused by "Allow Self Signed Certificates"

The data I have seen clearly shows that the current question about rejectUnauthorized is really confusing. @jelaplan, @tomofbroadcom what do you think?

[tomofbroadcom]

@VitGottwald so if I understood correctly you are suggesting to use "Allow Self Signed Certificates" instead of "Reject Unauthorised Certificates" (rejectUnauthorised)?

@dkelosky I understand why you did that and I'm usually for consistency between systems, even when it's not the optimal solution. But what needs to be said is, that the potential target audience of Zowe Explorer is quite broader and possibly less experienced in many ways, either with MF or distributed, than the audience of Zowe CLI.

Obviously it's hard to not agree with arguments of all of you. So, when writing any messages to user, it's only one-way and one-time communication with no other possibility to further explanation. Therefore it has to be on point, inform of what will be the impact and by careful wording also prevent any misunderstanding. Because if there is, it will be always our fail. This is something to have in mind when deciding in similar situations.

A quick way of checking the copy is to showing this to 3 people outside of the project or value stream with no explanation and let them to interpret it for you to see how it could be understood and why.

[jellypuno]

Another possible approach is to convert it into a question. Like "Are you using a certificate?" or "Do you have a certificate?" if Yes ru: true else NO ru: false.

[jellypuno]

Duplicate of #863

[MikeBauerCA]

The data I have seen clearly shows that the current question about rejectUnauthorized is really confusing.

Agreed. @dkelosky @VitGottwald any thoughts on the language suggested in #863? But, I would still prioritize eliminating the need for the question entirely for most users as we plan to do.

The prompts for base-path, encoding, and TSO servlet timeout are likely troublesome for users as well. Here is a gif of a previous experience I had (perhaps this has already been improved): https://github.com/zowe/vscode-extension-for-zowe/issues/1124#issuecomment-757990164

[dkelosky]

The data I have seen clearly shows that the current question about rejectUnauthorized is really confusing.

Can you share this data (along with the questions asked, roles of the respondents, sample size)?

"Allow Self Signed Certificates"

This is an incorrect description of what rejectUnauthorized means. In the context of security for mainframe users, we need to be precise so that the exact meaning and implication of using this setting is understood.

rejectUnauthorized is not the only answer for "solving" certificate problems.

the profile field name should be called rejectUnauthorized.

This would mean our profile and CLI args would use rejectUnauthorized (and support the built-in env var NODE_TLS_REJECT_UNAUTHORIZED) while our ZE dialogs would use some other description. Our strategy is to steer users to directly edit their configuration files; inevitably we'll expose them to rejectUnauthorized anyway.

Thank you @VitGottwald & @tomofbroadcom for the discussion. I don't want to defend rejectUnauthorized but convey all the implications of any proposed change.