Invitation of tenders
printable version (10 pages)
for improving a collaborative map editor
in context of a SSEDAS-TransforMap joint venture
This document provides a requirements analysis for usability enhancements and feature requests within the mapping component of the european SSEDAS project, represented by Get Active (Austria). It has been written by Ecobytes (Germany) and provides an invitation to tender a deliverable-oriented way of development to be used in Q3/4 2017 onwards to produce features that enhance the User Experience (UX) of the TransforMap Testbed. It is built from two sources:
The document is divided into three parts: functional requirements, technical requirements and business requirements. Within the functional requirements, the focus is placed on the expected user experience. The technical requirements describe the technology and tasks to deliver the user story, while attempting not to be opinionated on technical choices. The business requirements establish a community procurement process, estimated timeframes and budgeting agreements based on the individual deliveries.
The process described is part of a series of funding rounds that aim at building a mapping commons about alternative economies. This mapping commons is conceived as a federated, free and open infrastructure within the Public Domain. It stems from principles formulated within the Charter for Building a Data Commons for a Free, Fair and Sustainable Future. An introductory reading on the role of collective mapping and federation in Transformap is found on the article Leave it to the user: collectively shaping taxonomies to express plurality of narratives.
As the expected outputs will be implemented within existing infrastructure, further information on the Transformap testbed architecture and the listing of which web services exist are recommended reading. There you will find an overview of components, their interaction and links to source code, if available.
In this iteration we want to focus on the following artefacts:
- The Transformap map editor
- a forked editor adjusted for the SSEDAS project
in conjunction with
- the Transformap data service
The community can be reached in the transformaps discourse and on the
#transformap:matrix.allmende.io Matrix Channel. See also a post about the use of open collaboration platforms in Transformap.
User Story #410 - User login
Users of the editor should have their own login, in order to be able to add or edit data points.
The user should be given the opportunity to register/login via a trusted public identity provider (e.g. GitHub, Twitter), the Transformap Discourse or the Ecobytes Allmende Lab.
Furthermore, to identify fraud and allow for a revisions system (see #407) we intend to keep pseudonomised authorship logs, appended to every data set. The deployed solution should provide authentication for other services (e.g. base.transformap.co), too.
The interface will be simple and intuitive.
User Story #407 - History queries and restore function
As a user of the editor, I want to have access to POIs revision histories, in order to get an overview of changes and be given the choice to restore previous versions.
The API uses a data-model which persists a history of items alongside the individual datum. These history artefacts need to be retrievable by a logged in user.
The developed feature should provide a curational overview about users and their associated revisions, as well as POIs and the users and date of changes. This function is available to authenticated users.
To provide an improved user experience, a frontpage dashboard will be created to include a widget (event stream) of the latest changes (with direct links to the POI edition) and a call to action to add new POIs. A tutorial to guide the users into using the Transformap map editor will also be created for the page.
User Story #424 - Ability to add media to POIs
Logged in users should find an option within the map editor (creation/edition) to attach media, in order be able to add media (pictures, audio, video) to POIs.
This is to be integrated in form of a button to add media in the POI editor form (replacing the current “Upload here”) and should allow the upload of files from local storage.
The button will open a lightbox, where the user is given the possibility of adding one or more attachments and/or links in a single step. Optionally, the user can add a title and description to these media items.
Each added item should create a new object stored in the Transformap infrastructure and be referenced from the POI object (a new version of the POI is created on the lightbox submission).
A function to link to embed external media providers (e.g. Vimeo, YouTube) can be prepared, but is not considered a hard requirement.
User Story #410 - User login
This feature will be provided through the implementation of an identity management system (IMS) for TransforMap, and its integration in the map editor.
This will be a starting feature for providing a long-term single sign-on platform development for identity and access management (IAM) that:
- is data privacy compliant,
- provides active circumvention of vulnerability,
- is security hardened and
- offers reliability.
The IMS will rely on public identity providers (such as GitHub, Twitter, Transformaps Discourse) in order to externalize the security aspects, such as anti-spam mechanisms, e-mail verification and privacy compliance. The concrete implementation of the IAM in the editor will check if the user is authenticated properly in order to provide access to add and edit POIs.
The identity providers will return the users pseudonym and email addresses that are used as Transformap user object, in order to provide the possibility for users to be contacted in the future (e.g. for announcements or notifications on changes/subscribed content). The editor is publicly available and POIs can be browsed. Login and register buttons will invite visitors to authenticate in order to perform changes.
The authorization server provides access tokens for the resource server. Upon authentication, the user stays in the same view of a POI or boundary box, yet is able to perform and save changes.
This task involves the deployment of an open source OpenID Connect provider that is integrated with an identity provider. It is necessary for generation and verification of authorization tokens for the resource server.
This task is about building the frontend in the browser, allowing successful authentication of a user against an identity provider. This authentication is veriefid with the OP to receive an implicit grant token to access the RS. Changes of data are saved with an author.
The resource server, in our case the data service, needs to be equipped with the ability to verify authorization tokens, provided by the RP, against the OP.
User Story #407 - History queries and restore function
The data service stores multiple revisions for its objects. These need to be made available by history queries for allowing the editor to restore previous versions.
In case of restoring an older version, history is never rewritten, but a new version is created. It includes an additional key with the UUID of the version restored. For this to work, the data service allows to retrieve arbitrary versions of a selected datum.
For visualization and navigation, an embeddable history stream will be presented as welcoming page to the editor. It shows at least these lists:
- all versions of a POI;
- changes by a certain user;
- recently added POIs;
- recently changed POIs.
This will involve producing request endpoints in the data service and additional database queries (CouchDB views). The data response should include at least the UUID, the author and date of creation for each revision.
The Transformap data service currently serves and stores objects based upon their UUID, while assigning UUIDs to revisions, which are stored seperately. Upon changing the current version, a new version object is created, its UUID is added to the array of revisions, and only then replacing the state of the actual object.
This workflow is asking for additions, in form of separate endpoints or query parameters, to allow retrieval of arbitrary revisions of POIs identified with UUIDs. As the data model is conceptualised as an append-only stream of events, no old versions need to be modified.
The Transformap Editor as a decoupled frontend to the dumb Transformap data service, which is more a simple JSON storage backend than an Application Programming Interface (API), carries the responsibility to mutate data streams and load them into different stores and displays. Similarily to the Transformap viewer, it uses SPARQL-requested RDF/JSON serializations from the collaborative thesaurus to render the user interface and to query the
/places/ endpoint of the data service for display of user-specified data dimensions.
Assuming the currently implicit dimension of revisions is sufficiently projected into machine-queryable interfaces at the data service, a revision review and restore display needs to be integrated within the editor. It comes in form of a welcome page that gives an overview about recent activity within the overall wealth of geodata, but also specificly showing the create and edit history of a logged in user.
In case a user is freely editing an existing POI, the interface offers an option to review preexisting versions and, in case of need, to restore them to a new revision, keeping a reference to its origin version with the new datum. This is dependent on User Story 410.
The combined interaction of the Transformap Editor on top of the implicitly present data service is documented and shown in an explanatory tutorial for end users, forming a part of an overall user’s manual.
User Story #424 - Ability to add media to POIs
POIs in Transformap can be attached with URIs of media, which will be displayed accordingly by the Viewer. To improve the usability of the attachment workflow, an open source digital asset management system will be integrated with the Testbed.
This system will provide a central store for various media types (images, audio, video) and be integrated into the Editor. The Viewer is already prepared to display arbitrary media from accessible resources on the open web, denoted by an URI.
Where read access is granted libre, due to Public Domain or Creative Commons licencing of media, write access to the media store will only be granted upon authentication against the IMS. These federated write actions become necessary, when a user wants to add media via the Editor instead of the dedicated interface of the media management system.
Ideally, it should also allow for presenting usage statistics, federation of content with compatible softwares, distributed storage on peer to peer networks as well as RDF (Resource Description Framework) and IIIF (International Image Interoperability Framework) metadata.
This task involves the development and deployment of a social media management system for collaborative curation of media artefacts. It supports multiple media types, at least images, audio and video, and provides meaningful metadata about the assets, namingly a suitable license for TransforMap (i.e. MediaWiki, PD, CC; © only in special cases with exhausting license agreement) and canonical URIs (permalinks) for each entry.
The items presented to the user will be versioned and their revision history accessible to the end user. While those are interacting with a human-readable web user interface, daemons and services can interact with the application via a RESTful API. This API will receive authorization tokens from an arbitrary, configurable OP and act as another RS within the single sign-on IMS.
An embedded widget for media curation provided by the MMS is desirable.
The Media Management System (MMS) will be fully integrated into the user interface of the Editor. The federated single sign-on backend is used to receive authorization grants for the media RS and eventually write to it.
When a user adds or edits a POI, a button is presented to invoke the media management workflow, including choice or editing of already present media, upload of new items or deletion of false entries to a moderated trash. All metadata requirements from Task 426 apply here, too.
Embedding links to media on public platforms (YouTube, Vimeo, flickr, Instagram, archive.org, Dailymotion, …) that carry suitable licenses via OEmbed or similar means is desirable.
Continuing to use direct URIs of media with cleared rights may not be prohibited.
Due to the federated design of the single sign-on service, identities can be reused on multiple sites. By using a common identity, the user should be able to login to the media management system using the same credentials used for other Transformap services.
This task is about the integration of the independent MMS with the OpenID Connect Provider (OP) from above as Relying Party (RP) itself and as Resource Server (RS) for third-party services, such as the Editor. Users of the MMS can authenticate with their third-party identity at the OP (Task 425), or are being authenticated automatically via federated single sign-on. The MMS then acts as a Relying Party.
The business procedure of Transformap, as outlined in the introduction, differs from classical market logic. It is embedded into an ecosystem of communities of practice within the fields of socio-ecological activism for a free, fair and open society, civic self-organisation and climate justice, but also Open Data and FLOSS. Yet we operate within the given legal and cultural frameworks and aim at bridging these diverse experiences to the public sphere.
In doing so, we are proposing the present document as a guideline for enabling a community-driven mapping process for collective commoning. It stems from an available project budget and seeks to divest the resources, while commiting to an accountable, delivery-oriented work mode. This process is constrained by the following factors, derieved from project-oriented collaboration agreements:
invitation timeframe: 2 weeks, from June 01 to June 16, 2017
implementation timeframe: June to September 2017
overall budget: EUR 6.000,00 (from a Google Spreadsheet, line 25ff)
The tender process is disclosed publicly on the Transformap community platform. It is similarily designed to previous redistribution attempts of #communities:community-buckets.
Instead of a call for bids, you are reading a call for collaboration interests, why the harvesting of offers happens publicly. If you intend to answer to this invitation for tender, please direct your response at the #projects:procurement category, or send it there via email to
Please note offers have to be licenced as Creative Commons or Public Domain, as they are intended for a public review process.
By the hybrid nature of the process, community members and project stewards review the offers together, discuss the presented scopes and choose suitable combinations for awards of contract. Therefore offers may cover only a certain User Story, combinations of them or individual tasks, with combinations alike.
Payments will occur in parts upon tested delivery of user story features specified below. Testing will include a community review process, by SSEDAS partners and the Transformap community, of at least 5 working days.
EUR 2.250,00 User Story #410 - User login
EUR 750,00 Task #425 - Deployment of an OpenID Connect Provider (OP)
EUR 750,00 Task #415 - Building the editor authentication as Relying Party (RP)
EUR 750,00 Task #416 - Building the API authorization at Resource Server (RS)
EUR 2.000,00 User Story #407 - History queries and restore function
EUR 900,00 Task #418 - Implementing endpoints for retrieving arbitrary versions
EUR 900,00 Task #419 - Building an interface for restoring versions
EUR 200,00 Task #422 - Documenting the workflow for accessing and reverting revisions
EUR 1.750,00 User Story #424 - Ability to add media to POIs
EUR 500,00 Task #426 - Deployment of FLOSS document management system
EUR 750,00 Task #427 - Integration with editor
EUR 500,00 Task #428 - Integration with single sign-on service
When answering to this call for collaboration, please include information about:
- Name of the legal entity which should be attributed and awarded for the contribution(s)
- Link to representative web page and/or GitHub profile
- Choice of User Story(s) and/or Task(s)
- Justification and previous work experience related to the subjects chosen
- Short sketch of implementation plan
- Free Culture license
Then we should be good to go for broad discussion of the incoming proposals. If the community and project stewards award yours for implementation, further collaboration will be coordinated directly in the Taiga User Stories/Tasks.
We are excited to engage with you in this next iteration of building the TransforMap Commons and hope for fruitful collaboration!
This work is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License by Jon Richter, June 2017.