The Teamwork Framework

The Teamwork Framework (TTF) is a key component of TopBraid EDG for different types of data assets or vocabularies.

For example, an asset collection type to work with SKOS-based Taxonomies consists of pages to create a new taxonomy, to manage user permissions, to track and review changes, to edit the taxonomy itself, to produce various reports and to run data exports and imports. Many of these capabilities are also applicable to other kinds of asset collections, not just SKOS taxonomies. The role of TTF is to generalize those capabilities so that it becomes more efficient to develop similar asset collection types in a componentized way.

Overview of the Teamwork Framework

Asset collections consist of two workspace files that connect to a database for data storage. The first database contains the actual data of the “master” graph. The second database, ending with .tch contains metadata that is used to keep track of changes, permissions and other vocabulary specific settings.

The teamwork asset collection types (sometimes called “project types”) are the kinds of models that are available to the end user.

Each collection type is defined as a plugin to the teamwork framework. In a nutshell, each vocabulary type is backed by an instance of the class teamwork:ProjectType which is stored in a .ui.ttlx file and points to the specific plugins and other features that distinguish this collection type from others. If you are interested in adding your own vocabulary types, see Custom Asset Collection Types. You can also modify features available for the pre-defined vocabulary types.

EDG home pages list all installed vocabulary/asset types. When users click on the available type, they see a list of all vocabularies/assets of that type. From there, they have access to the available features.

Anatomy of a Teamwork Asset Collection

A combination of two related graphs, one containing the data and another one containing the change history of the data plus other information, is called a Teamwork project. This should not to be confused with the term project when used as top-level folder of the workspace. When using EDG, every vocabulary/asset is a Teamwork project. For the purposes of this discussion, asset collection is synonymous with Teamwork project.

Each asset collection type consists of two graphs that have corresponding connection files in the TopBraid workspace. You can query those graphs using any of the available query languages like SPARQL or from TopBraid EDG Studio from the Base URI Management admin page.

The master graph (e.g. XY.xdb) contains the actual data such as the edited SKOS concepts, also known as a “production copy”. The TCH (or team) graph (e.g. XY.tch.xdb) contains metadata about the project, including the change history, available workflows, user permissions and comments. TopBraid identifies Teamwork projects by their graph URIs: urn:x-evn-master:XY is the master graph for the vocabulary with the short id “XY”. Its metadata would be stored in urn:x-evn-master:XY.tch. The teamwork namespace contains SPARQL functions that can be used to derive those URNs from ids and to extract ids from a given URN. These functions are the preferred way of working with those graphs.

The project id (sometimes called graph id) is the short name of the vocabulary, usually consisting of letters only.

Permissions

All users with access to the surrounding TopBraid server can log into the EDG pages. However, who is allowed to do what can be controlled by the system administrator as well as the corresponding asset collection managers.

Teamwork supports the following three roles per vocabulary:

  • viewer: can only view a vocabulary or workflow, and make comments

  • editor: same as viewer but also has editing rights to make changes to a collection or workflow

  • manager: same as editor but also has administrative control over a collection or workflow, including the permission to grant or deny permissions to other users.

Any user can create a new collection, and will become its initial manager. At any given time, there must be at least one manager per asset collection. The Roles tab of the collection can then be used to grant additional permissions to other known users. All of those permissions are stored in the TCH graph. For example if Administrator is the manager of the asset collection with the id XY, then the TCH graph will contain the following triple:

<urn:x-evn-master:XY.tch> teamwork:manager <urn:x-tb-users:Administrator>

As shown above, the URIs of the users are always following the same pattern. Use the SPARQL function smf:currentUserName() to access the currently logged in user, and smf:userWithName(?userName) to construct the user URIs as above.

In addition to assigning permission roles to individual users, it is also possible to assign them to security roles. The UI provides simple drop down boxes for this. In terms of the internal RDF representation in the TCH graph, a security role is represented with a URI such as urn:x-tb-role:ROLE.

You can get the union of all master graphs that the given user (in the example, Administrator) has at least read access to by using special named graphs of the pattern urn:x-evn-union<:user>. For example, urn:x-evn-union:Administrator. This can be convenient for global search across multiple graphs. Note that such graphs are strictly read-only.

Change tracking

A change is an atomic unit of modifications to a given graph. They are usually created by the user through buttons and menu items such as the Create Concept buttons in EDG or the Save Changes button of the edit forms. Whenever the user sends such a request to the server, the master or workflow graph will be updated and the TCH graph will be updated with a new instance of teamwork:Change. An example Change object is shown below (in Turtle):

 1<urn:x-change:2013-04-03T00-32-05.915ZAdministrator>
 2    a teamwork:Change ;
 3    rdfs:comment "Create Class with URI http://example.org/vocabulary1/ExampleClass"^^xsd:string ;
 4    dcterms:created "2013-04-03T00:32:05.915Z"^^xsd:dateTime ;
 5    sioc:has_creator <urn:x-tb-users:Administrator> ;
 6    teamwork:added [
 7        teamwork:object owl:Class ;
 8        teamwork:predicate rdf:type ;
 9        teamwork:subject <http://example.org/vocabulary1/ExampleClass>
10    ] ;
11    teamwork:added [
12        teamwork:object "Sub3"^^xsd:string ;
13        teamwork:predicate rdfs:label ;
14        teamwork:subject <http://example.org/vocabulary1/ExampleClass>
15    ] ;
16    teamwork:added [
17        teamwork:object owl:Thing ;
18        teamwork:predicate rdfs:subClassOf ;
19        teamwork:subject <http://example.org/vocabulary1/ExampleClass>
20    ] ;
21    teamwork:status teamwork:Committed .

This is a set of changes indicating that the user:

  • Created a new class with the id http://example.org/vocabulary1/ExampleClass

  • Set the label of the new class to “Sub3”

  • Made the class a subclass of owl:Thing

A change may also point to a workflow via teamwork:tag if it has been made while the user was editing a workflow. Each added or deleted triple is stored in reified form via teamwork:subject, teamwork:predicate and teamwork:object as shown above. This makes it possible to find all changes for a given resource via a SPARQL query over the TCH graph. Note that teamwork:deleted is used to point at triples that were deleted.

The teamwork:status triple of a change indicates whether the change has been committed to the master copy or whether it only exists in a workflow – in which case the value would be teamwork:Uncommitted.

workflows (tags)

A workflow (internally often called tag) is a specific collection of changes that have been made to the master graph, but have not been saved in the master graph. Since all these changes are stored only in the TCH graphs, the workflow is a virtual construct that is computed on demand only. TopBraid has a mechanism that can temporarily apply a set of changes to an RDF graph (without modifying the underlying graph). All changes that are part of a workflow are associated with the workflow via the property teamwork:tag.

In order to access a specific workflow for a given graph (with id “XY”), and tag “myTag”) use a graph URI such as urn:x-evn-tag:XY:myTag:Administrator. In general, although it is possible to create such URIs “manually”, the preferred mechanism is through the SPARQL functions teamwork:getQueryGraph or teamwork:queryGraph as in the following example:

1SELECT ?concept
2WHERE {
3    BIND (teamwork:queryGraph(true, "XY", "myTag", "Administrator") AS ?graph) .
4    GRAPH ?graph {
5        ?concept a skos:Concept .
6    }
7}

Comments and Tasks

EDG has features to add a comment and/or task to the currently selected resource. These items are stored in the TCH graph, as instances of sioc:Post where the sioc:about property points at the resource.

Hint

You can explore details of the specific RDF triples by looking at the TCH graphs.