|
|
|
# Sharing Plattform Connector Interface (V0.1)
|
|
|
|
|
|
|
|
In order to integrate functionality from other services into the sharing platform, the sharing platform provides a **connector interface** to exchange information with theses services.
|
|
|
|
|
|
|
|
Potential usage scenarios could be:
|
|
|
|
- export one or more exercises (meta data of the complete git project into other platforms (e.g. into Artemis)
|
|
|
|
- support the generation of pdf-documents from a selection of latex exercises
|
|
|
|
- implement own search interfaces
|
|
|
|
|
|
|
|
## Concepts
|
|
|
|
|
|
|
|
### Basics
|
|
|
|
A **Connected Service** is a web service on its own. I.e. it runs independently from the sharing platform in its own environment.
|
|
|
|
The Connected Service communicates with the sharing platform via the **Connector Interface**. The Connector Interface is a set of dedicated web services and also some protocols that involve redirects via the web browser of the user.
|
|
|
|
|
|
|
|
A Connected Service may support various **actions**. Each action provides is own callback url.
|
|
|
|
|
|
|
|
It is in the responsibility of the connector, to ensure the authentication and/or authorization of the user, if needed.
|
|
|
|
Some interfaces may require explicit authentication of the user of the connected service. A user is typically authenticated by a valid oAuth2-token of the backbone gitlab system.
|
|
|
|
|
|
|
|
### Configuration
|
|
|
|
|
|
|
|
An administrator of the sharing platform registers a _connector action_ (with a given plugin-URL).
|
|
|
|
|
|
|
|
This plugin-URL is used to retrieve further json-encoded configuration data for the action and to transfer callback information for the sharing plattform by invoking the registered URL with further parameters (e.g. `https://artemis.codeablity.uibk.ac.at/api/sharing/config?apiBaseUrl=http://localhost:8080/api/&installationName=SharingPlatformTest`):
|
|
|
|
|
|
|
|
```json
|
|
|
|
{
|
|
|
|
"version" : "0.1", // the version of the supported sharing plattform interface (currently fixed at 0.1)
|
|
|
|
"pluginName" : "Artemis Sharing Connector", // The name of the plugin
|
|
|
|
"actions" : [ { // list of supported actions
|
|
|
|
"actionId" : "Import", // the id of the action
|
|
|
|
"actionName" : "Import to Artemis", // the name of the action (displayed in the web browser)
|
|
|
|
"actionTransferURL" : "/sharingImport", // a call back url, to initiate the action (absolute, or relative to the URL of
|
|
|
|
// this configuration.
|
|
|
|
// a filter expression (formulated in Java EL) to select the exercises on the plattform
|
|
|
|
// to which the action is applicable
|
|
|
|
"filterELExpression" : "metadata.type.externalName=='programming exercise'"
|
|
|
|
} ]
|
|
|
|
}
|
|
|
|
```
|
|
|
|
|
|
|
|
When invoking the configuration, the sharing plattform transfers additional request parameters (and authorization headers) for further information:
|
|
|
|
- apiBaseUrl: the base url for the call backs to the sharing plattform (e.g. ´https://sharing.codeability-austria.uibk.ac.at/api´)
|
|
|
|
- installationName: an informative name for the current installation (e.g. `sharing plattform (prod)`
|
|
|
|
- optional: an a `Authorization` header: an optional bearer security token
|
|
|
|
|
|
|
|
|
|
|
|
### Exchanged Data
|
|
|
|
|
|
|
|
The Plugin Interface will exchange various data. A description of the REST Api can be found at https://search.sharing-codeability.uibk.ac.at/swagger-ui/index.html (_at the time of writing under preparation_)
|
|
|
|
|
|
|
|
The main information item transferred is the shopping basket:
|
|
|
|
|
|
|
|
- **User**: Information about the requesting user
|
|
|
|
- **ShoppingBasket**: the currently selected items to be shared
|
|
|
|
- **ExerciseInfo**: Contains metadata about the exercise (coverage to be defined). And a reference to the GitLab URL
|
|
|
|
|
|
|
|
```plantuml
|
|
|
|
|
|
|
|
class User {
|
|
|
|
String email
|
|
|
|
}
|
|
|
|
' note top of User : Users should be authenticated via OAuth2 (authenticationURL)
|
|
|
|
|
|
|
|
class ShoppingBasket {
|
|
|
|
}
|
|
|
|
class Exercise {
|
|
|
|
String title
|
|
|
|
String gitLabURI
|
|
|
|
String gitLabProjectId
|
|
|
|
String[] keywords
|
|
|
|
}
|
|
|
|
|
|
|
|
User -> ShoppingBasket
|
|
|
|
ShoppingBasket "1" *-- "many" Exercise
|
|
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
- **SearchRequestDTO**: Query and User Information for a search via the sharing platform
|
|
|
|
- **UserPrincipal**: name and (optional) gitLabAccessToken for information retrieval
|
|
|
|
- **SearchInputDTO**: the search query
|
|
|
|
- **SearchInputMetadataDTO**: search query on meta data
|
|
|
|
- **SharingResultsDTO**: Results of a query (paged by page size of 10)
|
|
|
|
- **SharingResultDTO**: A single search hit
|
|
|
|
- **GitProject**: Information about the git project containing this hit
|
|
|
|
- **MetadataFile**: Information about meta data file
|
|
|
|
- **UserProvidedMetadataDTO**: the meta data itself
|
|
|
|
|
|
|
|
```plantuml
|
|
|
|
|
|
|
|
class SearchRequestDTO {
|
|
|
|
}
|
|
|
|
|
|
|
|
class UserPrincipal {
|
|
|
|
}
|
|
|
|
class SearchInputDTO {
|
|
|
|
}
|
|
|
|
class SearchInputMetadataDTO {
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
|
|
SearchRequestDTO --> SearchInputDTO
|
|
|
|
SearchInputDTO --> SearchInputMetadataDTO
|
|
|
|
SearchRequestDTO -down-> UserPrincipal
|
|
|
|
|
|
|
|
class SharingResultsDTO{
|
|
|
|
}
|
|
|
|
|
|
|
|
class SharingResultDTO{
|
|
|
|
}
|
|
|
|
class GitProject {
|
|
|
|
}
|
|
|
|
class MetadataFile {
|
|
|
|
}
|
|
|
|
class UserProvidedMetadataDTO {
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
|
|
SharingResultsDTO --> "0..10" SharingResultDTO
|
|
|
|
SharingResultDTO --> GitProject
|
|
|
|
SharingResultDTO --> MetadataFile
|
|
|
|
SharingResultDTO --> UserProvidedMetadataDTO
|
|
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
- **SharingPluginConfig**: configuration data of the Plugin (Metadata like name, description, ...). Information, which exercise types are supported.
|
|
|
|
|
|
|
|
```plantuml
|
|
|
|
|
|
|
|
|
|
|
|
class SharingPluginConfig {
|
|
|
|
String version (fixed to 0.1)
|
|
|
|
String pluginName
|
|
|
|
}
|
|
|
|
|
|
|
|
class Action {
|
|
|
|
String actionId
|
|
|
|
String actionName
|
|
|
|
String actionTransferURL
|
|
|
|
String filterELExpression
|
|
|
|
}
|
|
|
|
|
|
|
|
SharingPluginConfig "1" *-- "many" Action
|
|
|
|
|
|
|
|
```
|
|
|
|
The java binding of the interface is provided in https://sharing-codeability.uibk.ac.at/development/sharing/codeabilitysharingpluginapi
|
|
|
|
## Infrastructure
|
|
|
|
|
|
|
|
Typically a connected service provides its own web interface.
|
|
|
|
|
|
|
|
The communication between the sharing platform and the connected service is done via a REST service.
|
|
|
|
|
|
|
|
## Exchange Protocol
|
|
|
|
|
|
|
|
### Main action initiation logic
|
|
|
|
|
|
|
|
When the filter condition matches on an exercise, the user can invoke the respective action on the exercise: e.g. here the export action for Artemis on all exercises that have the format artemis.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
An action is typically invoked by redirecting the web browser in the sharing platform to the actionTransferURL.
|
|
|
|
The actionTransferURL is extended by the basket token and the following query parameters, to be processed further by the plugin:
|
|
|
|
- **apiBaseURL**: the baseURL for the plugin REST api. All REST requests should be made relative to this URL
|
|
|
|
- **returnURL**: an URL to be optionally used, to redirect the browser back to the sharing plattform.
|
|
|
|
(e.g. http://artemis.codeability.uibk.ac.at/sharingImport/6321ab93-e597-4afe-a675-9c3e695814da?returnURL=http://artemis.codeability.uibk.ac.at&apiBaseURL=http://localhost:8080/api/pluginIF/v0.1)
|
|
|
|
**Remark**: Due to browser restriction the plugin URL is currently not loaded in a separate window, but in the same window, replacing the sharing plattform web page.
|
|
|
|
|
|
|
|
|
|
|
|
```plantuml
|
|
|
|
package "Sharing Platform" {
|
|
|
|
[Sharing Web Page] .. () "WebInterface S"
|
|
|
|
() "WebInterface S" -- [Sharing Platform]
|
|
|
|
[Sharing Platform] - () "REST Interface S"
|
|
|
|
}
|
|
|
|
package "plugin" {
|
|
|
|
[Plugin Web Page] .. () "WebInterface P" : "(2) GET"
|
|
|
|
() "WebInterface P" -- [Plugin Application]
|
|
|
|
() "REST Interface P" - [Plugin Application]
|
|
|
|
}
|
|
|
|
|
|
|
|
[Sharing Web Page] ..> [Plugin Web Page]: "(1) invoke via actionTransferURL (+ BasketToken + further Parameters)"
|
|
|
|
()"REST Interface S" <.. [Plugin Application] : "(3) get action parameters"
|
|
|
|
```
|
|
|
|
|
|
|
|
Below you find a sketch of the basic process of the the invocation of a plugin action.
|
|
|
|
The action is initiated by a browser-based forward to the plugin web page, that contains a token to identify the basket and the URI to call back the REST interface.
|
|
|
|
|
|
|
|
**Remark**: The process can also work completely without a web interface of the plugin. Then the actionTransferURL is just an invocation of an REST interface.
|
|
|
|
|
|
|
|
```plantuml
|
|
|
|
actor "User Browser"
|
|
|
|
|
|
|
|
== Initialization (and regular heart beat monitoring) ==
|
|
|
|
"Sharing Plattform" -> Connector : REST config URL
|
|
|
|
Connector --> "Sharing Plattform" : SharingPluginConfig
|
|
|
|
|
|
|
|
== Shopping Session ==
|
|
|
|
|
|
|
|
[-> "User Browser"** : start session
|
|
|
|
|
|
|
|
"User Browser"-> "Sharing Plattform" : fill shopping basket
|
|
|
|
|
|
|
|
"User Browser"-> "Sharing Plattform" : trigger Action
|
|
|
|
|
|
|
|
"Sharing Plattform" --> "User Browser": redirect to action.actionTransferURL + "/<basketToken>?" + "apiBaseURL="<apiBaseURL> + "&returnURL=..."
|
|
|
|
|
|
|
|
"User Browser"-> Connector : action.actionTransferURL + "/<basketToken>?" + ...
|
|
|
|
activate Connector
|
|
|
|
Connector -> "Sharing Plattform": REST <apiBaseURL>/basket/<basketToken>
|
|
|
|
"Sharing Plattform" --> Connector: ShoppingBasket
|
|
|
|
|
|
|
|
Connector -> Connector: evaluate Basket, do Work
|
|
|
|
activate Connector #DarkSalmon
|
|
|
|
Connector -> "Sharing Plattform": REST <apiBaseURL>/basket/<basketToken>/repository/<exerciseId>
|
|
|
|
"Sharing Plattform" --> Connector: Zipped repository (master, latest commit)
|
|
|
|
|
|
|
|
Connector --> "User Browser": Result (HTML, PDF, ..., further actions)
|
|
|
|
deactivate Connector
|
|
|
|
|
|
|
|
Connector --> "User Browser": Optional - redirect to <returnURL>
|
|
|
|
|
|
|
|
deactivate Connector
|
|
|
|
```
|
|
|
|
|
|
|
|
## REST interface provided by the sharing Plattform
|
|
|
|
|
|
|
|
You can find a description of the current API with Swagger-UI at https://search.sharing-codeability.uibk.ac.at/swagger-ui/index.html
|
|
|
|
|
|
|
|
The following REST services are provided: (**Remark**: https://sharing.codeability.uibk.ac.at/api/pluginIF/v0.1 is just an example REST url, this must be replaced by the *apiBaseURL* submitted via the actionTransferURL.)
|
|
|
|
|
|
|
|
1. https://sharing.codeability.uibk.ac.at/api/pluginIF/v0.1/basket/<basketToken>
|
|
|
|
returns the Shopping Basket for this basketToken.
|
|
|
|
2. https://sharing.codeability.uibk.ac.at/api/pluginIF/v0.1/basket/<basketToken>/repository/<exerciseId>
|
|
|
|
returns the zipped content of the current master branch of the exercise repository.
|
|
|
|
Please note, the content of the file currently contains the repository identically as the *download functionality* in the git lab repository, but the (redundant) main folder is eliminated. I.e. when unzipping the layout is identical iff cloned directly from the repository (however the .git information is missing).
|
|
|
|
3. https://sharing.codeability.uibk.ac.at/api/pluginIF/v0.1/page-details gets a SearchRequestDTO and returns the corresponding SearchResultsDTO.
|
|
|
|
|
|
|
|
|
