Skip to content

Use Cases & Requirements : Delegated UI

Jump to bottom
Andrew Berezovskyi edited this page Nov 1, 2018 · 1 revision

Status: gathering input (please provide)

Background

Many core integration scenarios in OSLC involve linking resources together. While links can be created programmatically, they're often created by a person using an application. Delegated UIs allow individuals to create links from within an application's UI and see more information about linked resources without leaving the application. Delegated dialogs and preview have been a part of OSLC since the 1.0 specs.

Purpose

This page explores some considerations and requirements for delegated UIs in OSLC 3.0. It assumes the basic use cases are the same as in earlier specifications, although we do propose one new use case: editor dialogs.

Organization of this document follows the guidance set out in OSLC Core-TC Editor's Handbook.

Use Cases

The following considerations are split into common categories of use cases. Some of the use cases provide some details to help get a full understand of the case and requirements it creates.

Tags used:

3.0 - proposed 3.0 content

backlog - proposed backlog content

TODO - outstanding action or question

General Considerations (All Uses)

  1. In addition to desktop browsers, need mobile-specific guidance

  2. Need to have embedded UI fragments to have same/similar style as embedding tool.

Configuration Context (All uses)

  1. Configuration Management spec will need the ability to pass configuration context to various OSLC operations, including delegated UIs. Note: should that context passing mechanism be defined at the Core level?

General (Dialogs)

  1. Need mechanism to embed a fragment of integrating-with tool UI for the purposes of creating a new resource or selecting an existing resource of a specific type.

  2. Need a way to provide size hints for embedded UI fragment

  3. Need to be able to have the dialogs react properly to resizing

  4. Need to support a frame communication protocol other than HTML5 postMessage(), such as windowName protocol. postMessage() is not available in all tools, such as those based on Eclipse or older browsers.

    • TODO:

    • Need to investigate impact. Providers could continue to support 2.0 windowName protocols for backwards compatibility if needed.

    • What rendering engine does the Eclipse SWT internal browser use?

    • If windowName is dropped, we might remove the fragment identifier to negotiate the protocol.

    • One issue with having more than one protocol: there is no way currently for a consumer to discover which ones a provider supports. 2.0 spec issue: There doesn't appear to be any MUST requirements for supporting dialog protocols.

  5. (mp) Chaining of dialogs (creating wizards from dialogs). Scenario: In OSLC Automation, a user might want to use a selection dialog to select an AutomationPlan, then be presented with an AutomationRequest creation dialog for that plan (or AutomationResult selection dialog, if appropriate). (One solution would be to encourage providers to include selection of those prior resources in their later selection dialogs, but allowing composition on the client side allows more flexibility).

    • I would expect to see a "next" button (and probably a "previous" button - although "previous" wouldn't undo any creation that was done), but in 2.0 the provider sets the button text so this would say "ok" or "select" or "create", and there would be no "previous" button.

    • If the provider already provides AutomationPlan selection on the AutomationRequest creation dialog, either the consumer app needs to know this and not include the AutomationPlan selection dialog in the wizard flow, or the AutomationPlan selection on the creation dialog needs to be suppressed (probably the former).

  6. (img) Constraints. See section "Dialogue Constraints" below.

Dialogue Constraints (img)

Clients of delegated UI may want to impose constraints on resources that are created/selected by that UI, e.g.,

  1. RM: only allow selection of requirements of type X. In this case, the delegated UI provider would filter out from the UI requirements which were not of type X.

  2. QM: select a test case which is part of test plan Y. Only test cases that are linked to the plan would be shown.

  3. Config Management: Adding a configuration contribution: Pick a contributionthat is not already contributed to that configuration.

In some cases, a "generate-and-test" approach can be feasible: whereby the UI provides a resource list, and then the observer of that UI tests each one to see that it satisfies the constraint. For (1,2) examples above, this is possible but leads to a poor user experience.

For some constraints the UI server is in a better position to implement the contraints. For example, to allow the client of the delegated UI to request that the UI server impose constraints. I am aware of existing implementations that address these requirements in a couple of different ways:

  • Support POST to the Delegated Selection UI (POSTed resource describes the constraints). The created resource is a delegated UI which imposes those constraints.

  • Support URL parameters on GET to the Delegated Selection UI (parameters describe the constraints). This resource is a UI which imposes those constraints.

However, these implementations are non-standard. (There are related behaviours, not part of this use case, related to usability, e.g., that a delegated UI should remember recently selected resources, or user "favourites" etc. where existing web techniques can and have been used.)

Discovery

  1. (mp) When a Client has requested the representation of a resource or container, they should already have the information on what delegated UIs are supported.

  2. (mp) A Client should be able to get the information on what delegated UIs are supported on a given resource without getting its full representation.

  3. (mp) A provider may have many containers. (These are probably in a parent container). When a Client requests a list of all these containers (e.g. the representation of a parent container) it should be possible for the server to include information on which of those child containers support which kinds of delegated UI.

Creation

  1. Embedded UI should have optimal way to communicate to embedding tool, when action is successful or canceled. When successful, providing the URL to the newly created resource and simple label.

  2. Often the embedding tool has some known data it wants to use to pre-fill a creation dialog. This may include such properties such as owner, title, description, relationships to other resources and so on.

    • TODO:

    • Consider adding a way to discover if a provider supports pre-fill. Maybe just HTTP OPTIONS?

  3. Clients need a way to programmatically discover what are valid properties for pre-filling a creation dialog.

  4. (mp) Clients that want to use a dialog to create a representation that is not yet persisted on the provider, but returned directly to the consumer to be persisted there. (e.g. to POST to a creation factory, or equivalent, at zero or more later times, possibly while the user is not present at those later times to use a delegated UI).

Selection

  1. See General (Dialogs), ability to provide a embeddable UI for purpose of selecting an existing dialog.

  2. Ability to host a dialog for purposes of finding or creating a resource (goal of find or create is within dialog, a combined purpose dialog)

Editor / State Transition

  1. Need to provide a UI fragment for purpose of embedding in another tool, with the purpose of editing a specified resource. Typical editor events would be needed to indicate when changes have or have not been saved (UI marking unsaved/dirty). From CM group. 3.0

  2. Need to indicate if the resource has been saved or end user is done with editing. It would be nice if it used something similar to what UI Dialogs used to indicate this. From CM group. 3.0

  3. Like editing, though the primary purpose would be associated with performing a state transition on resource types such as CM change requests. Related to OSLC actions. 3.0

Previews / Compact

  1. Given the URL of a resource, be able to efficiently get some simple presentation properties such as: label, icon

  2. Given the URL of a resource, be able to fetch an embeddable HTML fragment that shows a minimal or expanded representation of the resource

  3. Need resource formats that are easily and commonly consumable by modern clients, typically web browsers.

    • Considerations are JSON primarily, with a need for RDF/LD friendly formats such as JSON-LD. Note: considering switching from XML to JSON-LD for the the Compact resource representation. This media type should be easier to consume from within a browser, but also is an RDF format. 3.0

  4. Preview spec should be separately consumable without needing to implement all of OSLC and LDP

  5. Need previews for resources with no RDF representation (for instance, binary files)

Requirements

  1. JSON description

  2. XSS/SOP issues

References

Main links

Clone this wiki locally