The aim of the documentation is to describe a world, where different suppliers and services jointly produce ensembles, in which users can move smoothly.
This is also expressed in the documentation principles:
Keeping the user in mind.
The most important principle is to consider the user and the user's objectives. When the user’s motivations and requirements are at the centre of attention, we can produce services in an environment that meets the users’ needs and brings joy to the users’ lives.
Everything is open and free.
Anyone can utilise everything freely and openly.
Not just users, but also services can discuss with each other, exchange information and increase awareness. Ensure that any other service in the environment can connect to your service.
The community consists of all kinds of operators, who have the freedom to build and maintain their own systems for their own purposes. This freedom involves the obligation to comply with and develop the ECA Standard.
Assist in creating credible and effective documentation, services and environment. The documentation and services must be easy to use.
Let’s use existing material.
Let’s not reinvent the wheel, but use and develop existing documents, interfaces, services and technologies that have been tested in the right environment. Make your own share reusable for others to utilise.
Provide a reference implementation.
Along with the written documentation, the reference implementation that is open and free to all is final proof that the documented matter works and can be implemented.
The Structure of The Documentation
The ECA documentation is divided into four sub-sections: Stories, Services, Interfaces and Infrastructure. The sub-sections’ documentation has been written from the different operators’ perspectives and always in accordance with its intended purpose.
Documentation is written in English.
The stories are the lightest level descriptions of the purpose of the system and its functions - from the user's perspective. They begin from setting objectives. Who and what type are our users, and which user problem are we solving. The stories also answer questions, what are the users’ motivators for their operations, in what type of environment and in with what type of stakeholder service or system it will be used.
Stories describe all the relevant information, on which basis the desired user experience and functionality for the service can be planned. A story does not, however, describe a single service as such, but instead provides the user a visible ensemble with the different services and the relations necessary between them.
The service documentation describes the actual service’s functionality and structure. To support this, the standard includes a reference implementation, which can be used to test the standard’s reasonableness.
In the open source reference implementation, the services and necessary interfaces are maintained in accordance with the documentation. It works as support for different operators as they build their actual services. The standard does not require the services to be implemented in the same way as the reference implementation. The source code and other materials have been published with a license that allows free use, so if you wish, you may utilise them as the basis of your own service products.
The interfaces allow for ensembles that are built out of several services, which are pleasant and seamless for users to use. With the help of the interfaces, the services can communicate with each other and exchange information, in which case the compatible services can serve the users better.
A cutting-edge user experience is achieved with sufficiently uniform practices from one service to another. You can help achieve this by following the service design guidelines when creating your own service.
The documentation defines the services and the connections between them. Each service can operate independently and be produced by different operators. There can also be several with the documentation. In the documentation, the services’ and interfaces’ names are intentionally general and they do not take a position on a specific technology. Each box in the picture does not necessarily have to be a separate service.
On the right-hand side, in the image above, there are the components in accordance with the user details and centralised login solution’s definition. There may be several login services (Auth Source) and the login options they provide are available to all other services via a proxy (Auth Proxy) through one interface. The users can manage the login services they are using
via the management service (Auth Connector). There may be several user data sources (Auth Data Source) and the user data provided by them is available to other services via an interface provided by a centralised user data service (Auth Data).
In the image above, on the left within the dotted lines, there are the most important and most visible services for the user. Through the store service (Bazaar) users can obtain materials produced by all content providers (CMS) to use in other services (LMS). The terms CMS and LMS may be confusing, but they simply refer to the producer and the consumer. Services that produce anything and services that provide the user an opportunity to consume anything. The documentation does not take a more precise stand of what the two could be. In addition to these, there is a collective service (Recipes) which enables material to be compiled and discussed.
In the image above, at the bottom, there are Meta services, which collect and transmit (Meta Data) as well as analyse (Meta Analyzer) users’ activities.
Contributions and Development Status
The documentation is a living document, which is specified all the time. The reference implementation related to the documentation also lives and it is developed. Contributions and discussions mainly take place through Github. All discussions are aimed to be kept open for all to see.
Everyone can participate in the discussions in a fully transparent manner. The development mainly takes place in English, so all the discussions are in English. Nothing, however, prevents issues being made in Finnish also, they will also be processed.
The repos, progress of development and open issues are listed below.
Standard documentation source for http://docs.educloudalliance.org
- 21: Publisher and copyright information in LMS/CMS API
- 20: Demonstration videos of use cases
- 19: Description of the Auth Data service
- 18: Bazaar APIs based on Dikaios
- 16: Metadata and analytics
- 15: Learning analytics
- 14: Content metadata
- 13: New user registration
- 12: New user registration sequence
- 11: Description of the Auth Connector service
- 10: Group work and collaboration
- 9: Auth IF attributes
- 8: Authentication attributes study
- 3: Initial Edustore version
- 26: Do not return disabled userattributes
- 25: Query endpoint is returning disabled attributes
- 24: Attributes are not automatically created
- 23: Document settings.AUTH_EXTERNAL_SOURCES
- 21: Allow user search with multiple attributes
- 18: Better organisation of certificate files
- 17: ignore certificate file
- 13: LDAP external source results need paging
- 12: LDAP external sources need better error handling
- 10: Generate a fake OID for external users
- 8: Dream Platform support
- 7: LDAP support
- 6: External Data concept
- 5: Services can store attributes in the database
- 4: It should be possible to query only changed data from the API
- 29: Attribute query response from auth data is not paged
- 24: Media queries break when font resize buttons are used
- 21: Removing an authentication method in the profile page does not work
- 20: User must not be able to remove her last authentication method
- 19: Profile page must not display the auth hash
- 16: Increase test coverage
- 15: increase test coverage
- 12: Update Django to 1.8 LTS
- 10: Implement audit log for changes made to Auth Data
- 9: Limit invitee data query to municipality level