Make raiseIntent context optional

[Roaders]

Enhancement Request

Use Case

So far in the application that I am writing the only places where we raise an intent is purely to get the response. We have no need to send a context object so we have to use fdc3.nothing. I think that this is potentially confusing to newcomers to the standard and could well make them think that they are not able to use raise intent purely to get a response from another app.

We would also have to modify the IntentHandler to make context optional.

[kriswest]

Here are the past issues to read on this topic: #361, #1410 There are no doubt some meeting minutes to look at also. Also please check the jsdoc and reference docs (which are the same) for the relevant API calls, as they do cover fdc3.nothing use: https://fdc3.finos.org/docs/api/ref/DesktopAgent#raiseintent

We would also have to modify the IntentHandler to make context optional.

This is problematic when the second argument (contextMetadata) is about to become required (there will always be metadata returned). Changing argument order isn't desirable, so we would need to pass something concrete like null or fdc3.nothing.

Given the gotchas we ran into last time we discussed making context optional I think the best way forward is review of the past decision and a detailed proposal for change that addresses all potential impacts - or stick with the current setup based on fdc3.nothing. A middle ground might be having the desktop agent convert a null input to a nothing output... but I'm not sure it helps a lot.

[Roaders]

As we have a breaking change release in the works then perhaps this issue can be re-addressed in light of that. The issue can be resolved as an additive change (at least from the point of view of a Typescript application) and should not break any apps. It will only need minimal modification of getAgent() code in the DesktopAgentProxy and of preload desktop agents.

I propose that we change the existing function signature:

raiseIntent(intent: string, context: Context, app?: AppIdentifier): Promise<IntentResolution>;

and make the second argument optional:

raiseIntent(intent: string, context?: Context, app?: AppIdentifier): Promise<IntentResolution>;

we could also allow null as a value for context (but IMHO this is not needed):

raiseIntent(intent: string, context?: Context | null, app?: AppIdentifier): Promise<IntentResolution>;

If a consumer then wanted to call the function with no context and with specifying an app they would have to pass null or undefined as the second parameter:

agent.raiseIntent("StartCall", undefined, { appId: "my-app-id" });
agent.raiseIntent("StartCall", null, { appId: "my-app-id" });

If null or undefined is passed as the second argument then the DesktopAgentProxy would replace this value with the fdc3.nothing context. This will mean that none of the message schemas need to be changed and it will mean that any listeners will still get a context object and no refactoring to deal with possible null or undefined values will need to be done.

This will mean that if you just want to raise an intent with no context there is no need to pass an empty context:

agent.raiseIntent( "StartCall" );