|
|
# Sharing Plattform Connector Interface (V0.1)
|
|
# 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.
|
|
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:
|
|
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
|
|
- export one or more exercises (meta data of the complete git project into other platforms (e.g. into Artemis)
|
|
|
- implement own search interfaces
|
|
- support the generation of pdf-documents from a selection of latex exercises
|
|
|
|
|
- implement own search interfaces
|
|
|
## Concepts
|
|
|
|
|
|
|
For historical reasons the connector is also referred as "plugin".
|
|
|
### Basics
|
|
|
|
|
A **Connected Service** is a web service on its own. I.e. it runs independently from the sharing platform in its own environment.
|
|
## Concepts
|
|
|
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.
|
|
|
|
|
|
|
### Basics
|
|
|
A Connected Service may support various **actions**. Each action provides is own callback url.
|
|
|
|
|
|
|
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.
|
|
|
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.
|
|
A Connected Service may support various **actions**. Each action provides is own callback url.
|
|
|
|
|
|
|
|
### Configuration
|
|
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.
|
|
|
|
|
|
|
|
An administrator of the sharing platform registers a _connector action_ (with a given plugin-URL).
|
|
### Configuration
|
|
|
|
|
|
|
|
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`):
|
|
An administrator of the sharing platform registers a _connector action_ (with a given plugin-URL).
|
|
|
|
|
|
|
|
```json
|
|
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`):
|
|
|
{
|
|
|
|
|
"version" : "0.1", // the version of the supported sharing plattform interface (currently fixed at 0.1)
|
|
```json
|
|
|
"pluginName" : "Artemis Sharing Connector", // The name of the plugin
|
|
{
|
|
|
"actions" : [ { // list of supported actions
|
|
"version" : "0.1", // the version of the supported sharing plattform interface (currently fixed at 0.1)
|
|
|
"actionId" : "Import", // the id of the action
|
|
"pluginName" : "Artemis Sharing Connector", // The name of the plugin
|
|
|
"actionName" : "Import to Artemis", // the name of the action (displayed in the web browser)
|
|
"actions" : [ { // list of supported actions
|
|
|
"actionTransferURL" : "/sharingImport", // a call back url, to initiate the action (absolute, or relative to the URL of
|
|
"actionId" : "Import", // the id of the action
|
|
|
// this configuration.
|
|
"actionName" : "Import to Artemis", // the name of the action (displayed in the web browser)
|
|
|
// a filter expression (formulated in Java EL) to select the exercises on the plattform
|
|
"actionTransferURL" : "/sharingImport", // a call back url, to initiate the action (absolute, or relative to the URL of
|
|
|
// to which the action is applicable
|
|
// this configuration.
|
|
|
"filterELExpression" : "metadata.type.externalName=='programming exercise'"
|
|
// 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)`
|
|
When invoking the configuration, the sharing plattform transfers additional request parameters (and authorization headers) for further information:
|
|
|
- optional: an a `Authorization` header: an optional bearer security token
|
|
|
|
|
|
|
- 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)`
|
|
|
### Exchanged Data
|
|
- optional: an a `Authorization` header: an optional bearer security token
|
|
|
|
|
|
|
|
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_)
|
|
### Exchanged Data
|
|
|
|
|
|
|
|
The main information item transferred is the shopping basket:
|
|
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_)
|
|
|
|
|
|
|
|
- **User**: Information about the requesting user
|
|
The main information item transferred is the shopping basket:
|
|
|
- **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
|
|
- **User**: Information about the requesting user
|
|
|
|
|
- **ShoppingBasket**: the currently selected items to be shared
|
|
|
```plantuml
|
|
- **ExerciseInfo**: Contains metadata about the exercise (coverage to be defined). And a reference to the GitLab URL
|
|
|
|
|
|
|
|
class User {
|
|
```plantuml
|
|
|
String email
|
|
|
|
|
}
|
|
class User {
|
|
|
' note top of User : Users should be authenticated via OAuth2 (authenticationURL)
|
|
String email
|
|
|
|
|
}
|
|
|
class ShoppingBasket {
|
|
' note top of User : Users should be authenticated via OAuth2 (authenticationURL)
|
|
|
}
|
|
|
|
|
class Exercise {
|
|
class ShoppingBasket {
|
|
|
String title
|
|
}
|
|
|
String gitLabURI
|
|
class Exercise {
|
|
|
String gitLabProjectId
|
|
String title
|
|
|
String[] keywords
|
|
String gitLabURI
|
|
|
}
|
|
String gitLabProjectId
|
|
|
|
|
String[] keywords
|
|
|
User -> ShoppingBasket
|
|
}
|
|
|
ShoppingBasket "1" *-- "many" Exercise
|
|
|
|
|
|
|
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
|
|
- **SearchRequestDTO**: Query and User Information for a search via the sharing platform
|
|
|
- **SearchInputDTO**: the search query
|
|
- **UserPrincipal**: name and (optional) gitLabAccessToken for information retrieval
|
|
|
- **SearchInputMetadataDTO**: search query on meta data
|
|
- **SearchInputDTO**: the search query
|
|
|
- **SharingResultsDTO**: Results of a query (paged by page size of 10)
|
|
- **SearchInputMetadataDTO**: search query on meta data
|
|
|
- **SharingResultDTO**: A single search hit
|
|
- **SharingResultsDTO**: Results of a query (paged by page size of 10)
|
|
|
- **GitProject**: Information about the git project containing this hit
|
|
- **SharingResultDTO**: A single search hit
|
|
|
- **MetadataFile**: Information about meta data file
|
|
- **GitProject**: Information about the git project containing this hit
|
|
|
- **UserProvidedMetadataDTO**: the meta data itself
|
|
- **MetadataFile**: Information about meta data file
|
|
|
|
|
- **UserProvidedMetadataDTO**: the meta data itself
|
|
|
```plantuml
|
|
|
|
|
|
|
```plantuml
|
|
|
class SearchRequestDTO {
|
|
|
|
|
}
|
|
class SearchRequestDTO {
|
|
|
|
|
}
|
|
|
class UserPrincipal {
|
|
|
|
|
}
|
|
class UserPrincipal {
|
|
|
class SearchInputDTO {
|
|
}
|
|
|
}
|
|
class SearchInputDTO {
|
|
|
class SearchInputMetadataDTO {
|
|
}
|
|
|
}
|
|
class SearchInputMetadataDTO {
|
|
|
|
|
}
|
|
|
|
|
|
|
|
SearchRequestDTO --> SearchInputDTO
|
|
|
|
|
SearchInputDTO --> SearchInputMetadataDTO
|
|
SearchRequestDTO --> SearchInputDTO
|
|
|
SearchRequestDTO -down-> UserPrincipal
|
|
SearchInputDTO --> SearchInputMetadataDTO
|
|
|
|
|
SearchRequestDTO -down-> UserPrincipal
|
|
|
class SharingResultsDTO{
|
|
|
|
|
}
|
|
class SharingResultsDTO{
|
|
|
|
|
}
|
|
|
class SharingResultDTO{
|
|
|
|
|
}
|
|
class SharingResultDTO{
|
|
|
class GitProject {
|
|
}
|
|
|
}
|
|
class GitProject {
|
|
|
class MetadataFile {
|
|
}
|
|
|
}
|
|
class MetadataFile {
|
|
|
class UserProvidedMetadataDTO {
|
|
}
|
|
|
}
|
|
class UserProvidedMetadataDTO {
|
|
|
|
|
}
|
|
|
|
|
|
|
|
SharingResultsDTO --> "0..10" SharingResultDTO
|
|
|
|
|
SharingResultDTO --> GitProject
|
|
SharingResultsDTO --> "0..10" SharingResultDTO
|
|
|
SharingResultDTO --> MetadataFile
|
|
SharingResultDTO --> GitProject
|
|
|
SharingResultDTO --> UserProvidedMetadataDTO
|
|
SharingResultDTO --> MetadataFile
|
|
|
|
|
SharingResultDTO --> UserProvidedMetadataDTO
|
|
|
```
|
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
- **SharingPluginConfig**: configuration data of the Plugin (Metadata like name, description, ...). Information, which exercise types are supported.
|
|
- **SharingPluginConfig**: configuration data of the Plugin (Metadata like name, description, ...). Information, which exercise types are supported.
|
|
|
|
|
|
|
|
```plantuml
|
|
```plantuml
|
|
|
|
|
|
|
|
|
|
|
|
|
class SharingPluginConfig {
|
|
class SharingPluginConfig {
|
|
|
String version (fixed to 0.1)
|
|
String version (fixed to 0.1)
|
|
|
String pluginName
|
|
String pluginName
|
|
|
}
|
|
}
|
|
|
|
|
|
|
|
class Action {
|
|
class Action {
|
|
|
String actionId
|
|
String actionId
|
|
|
String actionName
|
|
String actionName
|
|
|
String actionTransferURL
|
|
String actionTransferURL
|
|
|
String filterELExpression
|
|
String filterELExpression
|
|
|
}
|
|
}
|
|
|
|
|
|
|
|
SharingPluginConfig "1" *-- "many" Action
|
|
SharingPluginConfig "1" *-- "many" Action
|
|
|
|
|
|
|
|
```
|
|
```
|
|
|
The java binding of the interface is provided in https://sharing-codeability.uibk.ac.at/development/sharing/codeabilitysharingpluginapi
|
|
|
|
|
## Infrastructure
|
|
The java binding of the interface is provided in https://sharing-codeability.uibk.ac.at/development/sharing/codeabilitysharingpluginapi
|
|
|
|
|
|
|
|
Typically a connected service provides its own web interface.
|
|
## Infrastructure
|
|
|
|
|
|
|
|
The communication between the sharing platform and the connected service is done via a REST service.
|
|
Typically a connected service provides its own web interface.
|
|
|
|
|
|
|
|
## Exchange Protocol
|
|
The communication between the sharing platform and the connected service is done via a REST service.
|
|
|
|
|
|
|
|
### Main action initiation logic
|
|
## Exchange Protocol
|
|
|
|
|
|
|
|
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.
|
|
### 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
|
|
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:
|
|
|
- **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)
|
|
- **apiBaseURL**: the baseURL for the plugin REST api. All REST requests should be made relative to this URL
|
|
|
**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.
|
|
- **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
|
|
|
```plantuml
|
|
package "Sharing Platform" {
|
|
|
package "Sharing Platform" {
|
|
[Sharing Web Page] .. () "WebInterface S"
|
|
|
[Sharing Web Page] .. () "WebInterface S"
|
|
() "WebInterface S" -- [Sharing Platform]
|
|
|
() "WebInterface S" -- [Sharing Platform]
|
|
[Sharing Platform] - () "REST Interface S"
|
|
|
[Sharing Platform] - () "REST Interface S"
|
|
}
|
|
|
}
|
|
package "plugin" {
|
|
|
package "plugin" {
|
|
[Plugin Web Page] .. () "WebInterface P" : "(2) GET"
|
|
|
[Plugin Web Page] .. () "WebInterface P" : "(2) GET"
|
|
() "WebInterface P" -- [Plugin Application]
|
|
|
() "WebInterface P" -- [Plugin Application]
|
|
() "REST Interface P" - [Plugin Application]
|
|
|
() "REST Interface P" - [Plugin Application]
|
|
}
|
|
|
}
|
|
|
|
|
|
|
[Sharing Web Page] ..> [Plugin Web Page]: "(1) invoke via actionTransferURL (+ BasketToken + further Parameters)"
|
|
|
[Sharing Web Page] ..> [Plugin Web Page]: "(1) invoke via actionTransferURL (+ BasketToken + further Parameters)"
|
|
()"REST Interface S" <.. [Plugin Application] : "(3) get action 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.
|
|
|
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.
|
|
|
|
|
|
|
|
**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"
|
|
|
```plantuml
|
|
|
|
|
actor "User Browser"
|
|
== Initialization (and regular heart beat monitoring) ==
|
|
|
|
|
"Sharing Plattform" -> Connector : REST config URL
|
|
|
== Initialization (and regular heart beat monitoring) ==
|
|
Connector --> "Sharing Plattform" : SharingPluginConfig
|
|
|
"Sharing Plattform" -> Connector : REST config URL
|
|
|
|
|
Connector --> "Sharing Plattform" : SharingPluginConfig
|
|
== Shopping Session ==
|
|
|
|
|
|
|
|
== Shopping Session ==
|
|
[-> "User Browser"** : start session
|
|
|
|
|
|
|
|
[-> "User Browser"** : start session
|
|
"User Browser"-> "Sharing Plattform" : fill shopping basket
|
|
|
|
|
|
|
|
"User Browser"-> "Sharing Plattform" : fill shopping basket
|
|
"User Browser"-> "Sharing Plattform" : trigger Action
|
|
|
|
|
|
|
|
"User Browser"-> "Sharing Plattform" : trigger Action
|
|
"Sharing Plattform" --> "User Browser": redirect to action.actionTransferURL + "/<basketToken>?" + "apiBaseURL="<apiBaseURL> + "&returnURL=..."
|
|
|
|
|
|
|
|
"Sharing Plattform" --> "User Browser": redirect to action.actionTransferURL + "/<basketToken>?" + "apiBaseURL="<apiBaseURL> + "&returnURL=..."
|
|
"User Browser"-> Connector : action.actionTransferURL + "/<basketToken>?" + ...
|
|
|
|
|
activate Connector
|
|
|
"User Browser"-> Connector : action.actionTransferURL + "/<basketToken>?" + ...
|
|
Connector -> "Sharing Plattform": REST <apiBaseURL>/basket/<basketToken>
|
|
|
activate Connector
|
|
"Sharing Plattform" --> Connector: ShoppingBasket
|
|
|
Connector -> "Sharing Plattform": REST <apiBaseURL>/basket/<basketToken>
|
|
|
|
|
"Sharing Plattform" --> Connector: ShoppingBasket
|
|
Connector -> Connector: evaluate Basket, do Work
|
|
|
|
|
activate Connector #DarkSalmon
|
|
|
Connector -> Connector: evaluate Basket, do Work
|
|
Connector -> "Sharing Plattform": REST <apiBaseURL>/basket/<basketToken>/repository/<exerciseId>
|
|
|
activate Connector #DarkSalmon
|
|
"Sharing Plattform" --> Connector: Zipped repository (master, latest commit)
|
|
|
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": Result (HTML, PDF, ..., further actions)
|
|
|
|
|
deactivate Connector
|
|
Connector --> "User Browser": Optional - redirect to <returnURL>
|
|
|
|
|
|
|
|
Connector --> "User Browser": Optional - redirect to <returnURL>
|
|
deactivate Connector
|
|
|
|
|
```
|
|
|
deactivate Connector
|
|
|
|
|
```
|
|
## REST interface provided by the sharing Plattform
|
|
|
|
|
|
|
|
## 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
|
|
|
|
|
|
|
|
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.)
|
|
|
|
|
|
|
|
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/ returns the Shopping Basket for this basketToken.
|
|
|
|
|
2. https://sharing.codeability.uibk.ac.at/api/pluginIF/v0.1/basket//repository/ 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).
|
|
|
1. https://sharing.codeability.uibk.ac.at/api/pluginIF/v0.1/basket/<basketToken>
|
|
3. https://sharing.codeability.uibk.ac.at/api/pluginIF/v0.1/page-details gets a SearchRequestDTO and returns the corresponding SearchResultsDTO. |
|
|
returns the Shopping Basket for this basketToken.
|
|
\ No newline at end of file |
|
|
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.
|
|
|
|
|
|
|
|
|
|
|
|
|
