Add FDC3 API entry point as part of standard about fdc3

[rikoe]

@thorsent I don’t actually think versioning is a problem if there are no breaking changes in the API - for 1.1 everything is just extensions to the 1.0 interfaces.

Explicitly being able to request the version could be helpful though, in which case I definitely prefer the API method to the versioned object one - although this is something that vendors could provide without explicit standard support...

[nkolba]

@nicholasdgoodman this is good point about non-web implementations. The PR related to this issue is specific though: "In the case of web applications, a Desktop Agent SHOULD provide the FDC3 API via a global accessible as window.fdc3. Implementors MAY additionally make the API available through modules, imports, or other means."

As for multiple FDC3 agents on a single window, I'd like to understand this use case better. On the surface, I don't see how this would work from a UX, application development, or security standpoint.

[nkolba]

@rikoe . What would this look like in the spec? Something like...

"In the case of web applications, a desktop agent MUST provide the FDC3 API via a global accessible as window.fdc3. Implementors MAY additionally make the API available through module, imports, or other means."

[rikoe]

Yes. The reason for window.fdc3 is that it is the method with no other dependency on frameworks or methodologies, and should work in all browsers/scripts.

It is also a handy one-stop way to check if FDC3 is available/exposed or not.

I expect vendors may want to make available module imports etc. that exposes this in a nicer way, and that's fine.

[nkolba]

Added a PR #139

@rikoe

[thorsent]

Agree, this is a very important "last mile" piece that is necessary to get vendors comfortable writing to the standard.

I would recommend considering a versioning system to deal with the inevitable backward compatibility problem: window.fdc3.v1_0_0

or, an alternate way to deal with versioning is to push the responsibility to the client by providing a version retrieval function:

let version=FDC3.getVersion();
if(version<"1.2") console.log("Incompatible FDC3 version")

[thorsent]

One other consideration is initialization. Should we create a provision for a DesktopAgent to perform asynchronous initialization before FDC3 functions can be called:

FDC3.onReady(() => {
    // client does stuff now
});

or, should the provider be responsible for providing a truly static implementation that handles race conditions internally vis a vis queuing or some other mechanism?

[nkolba]

Thanks @thorsent. these are excellent points!

There is definitely an implicit handshake/provisioning between an app and the desktop agent today that is not part of the standard - and is where questions of version and other metadata would be handled. Putting more standards around this seems to make sense, feeling like this is a post 1.1. item though...

[nkolba]

Maybe combine onReady with version/desktop agent info object... e.g.

fdc3.onReady(info => {
if (info.version < "1.2") { ...}
});

[thorsent]

I like @nkolba's approach. It gives the developer the information they need to either opt out of a version that isn't compatible or provide a warning. Also useful for vendors who could override that info object with other meta data.

I think the success of the standard depends a great deal on trying to avoid creating backward and forward compatibility issues in the first place but it does seem inevitable when envisioning an ecosystem of hundreds of apps and desktop agents in the field that may be running various versions of an evolving standard.

[nicholasdgoodman]

I would recommend against this suggestion, as it seems to imply that the specification is to be confined within a browser. As someone who has written other language implementations of the protocol, it seems out of place -- there is no window object in C#, Node,

Also, it seems unnecessarily constraining to limit the number of FDC3 agents allowed on a specified window. Many apps (web or otherwise) have composite views with multiple tabs, docks, etc. all sharing the same window object. Are we to say they cannot have different context channels, broadcast to each other, or pass a StartChat intent from one <div> to another?

Finally, from my experience with front end frameworks like Angular and React - particularly with Typescript - the out of the box compilation tooling tends to have a difficult time handling global objects tied to the window object.

If implementors want window.fdc3 they should be responsible for doing it themselves.

[rikoe]

@nicholasdgoodman I disagree.

The suggested change to the standard says “should”, not “must”, so for environments where it doesn’t make sense, it can be excluded. Node is kind of irrelevant anyway, since FDC3 is a front-end concern at the moment.

I don’t understand how this suggestion “limits the number of FDC3 agents allowed on a specified window” - having multiple FDC3 desktop agents active in the same window or app at the same time is not something we really support, and I don’t think it would make sense for any part of the FDC3 API, really, to have the same operation provided simultaneously, so this doesn’t feel like a constraint.

Finally, I use global frameworks with global objects all the time, including OpenFin, Finsemble and Glue42, as well as Symphony. There are standard patterns and support for this kind of global object access in Angular, React and TypeScript, and I haven’t had a difficult time dealing with them, as you suggest is the case.

I think if we let everyone define the access point in a slightly different way, we don’t have a standard anymore, as accessing FDC3 will work differently depending on platform. Then we are back to the equivalent of browser agent checks to determine what environment we are running in...

I think it therefore makes sense to offer this standard entry point for web environments, which is the primary use case for FDC3 at the moment. It is web framework and web platform-agnostic, and in line with how vendor-specific interop access works today.

Adding it doesn’t make the standard more restrictive, in my opinion, it instead opens up its reach and accessibility.

[rikoe]

Addressed by #139

[nicholasdgoodman]

@nkolba @rikoe - sorry to comment late on a closed PR!

my final two comments regarding this would be that dictating window.fdc3 also places the burden on implementations to provide synchronous functionality, since ECMA properties are not await-able, or to throw errors if the window.fdc3 object is not in a "ready state".

as for multi-agent, bear in mind that contrary to mobile experience where full page single-context applications are the norm, on a desktop we should consider that an application may have multiple windows, and that a window may have multiple components, that a user may desire to assign different functionality each as if they were separate applications: