ART Dataset Editor

Revision as of 08:27, 8 July 2020 by Mligtvoet (talk | contribs) (Add a concept from a repository)
Tools.svg This article or section is in the middle of an expansion or major restructuring and is not yet ready for use. You are welcome to assist in its construction by editing it as well.

This text documents how datasets can be edited.

Log in and navigate to the dataset page

Perform the following steps:

  • Prerequisite: you need an account with the proper permissions to edit the project. Contact the project maintainer.
  • go to the ART-DECOR main page
  • Log into ART-DECOR by clicking Login at the top-right
  • select a project from the dropdown box DECOR
  • navigate to the Datasets tab

Building a dataset

A dataset is a list of (hierarchical) concepts, see also: DECOR-dataset.

Typically the first concepts created are concept groups which contain child concepts. Building a dataset is done by:

Setting dataset attributes

Set the dataset status

Datasets can have the following status:

  • draft: (yellow) the dataset is under development (nascent), not ready for production use. This is the initial status for new datasets.
  • final: (green) the dataset is finalized, and deemed fit for use.
  • rejected: (purple) the dataset is rejected. During the development proces it was decided that further development on this dataset will not happen.
  • cancelled: (blue) the dataset was never published and is withdrawn.

Below is a screenshot that displays the buttons to change the dataset status:

Error creating thumbnail: Unable to save thumbnail to destination

Set the dataset version label

The dataset version ia a human readable version number or version label for convenient human rendition; not used by an application. The version label can be altered by:

  • adding text in the textbox

En dataset 03.jpg

  • saving the version label by clicking on the button save
  • cancelling the edit by clicking on the button cancel

Set the dataset description

The dataset can optionally contain a human readable text that describes the dataset. Adding a dataset description is done by:

  • Clicking on description folds out a text editor

En dataset 04.jpg

  • Add text, and optionally use the text formatting tools.
  • You may optionally link to images or other web addresses.
  • Click on another textbox, for instance the name textbox
  • The form will now display the save and cancel buttons to save the description, or cancel the edit.

Concept attributes

Concepts have the following attributes:

  • Version: ART-DECOR enters a date when the concept is created
  • Id: ART-DECOR will assign an identifier for new concepts based on the dataset identifier
  • type: group or item. Groups can contain other concepts
  • Status, see Concept status machine
  • Name: A name for the artifact that will be meaningful to business or domain experts. One artifact may have different business name translations for each realm and/or language
  • Description: One to many descriptions per language
  • Source: human readable hint where this data element originally comes from
  • Rationale: human readable justification or explanation why this concept is present
  • Operationalization: how to measure, obtain, specify the value of an observation
  • Comment: One to many comments on the concept

Only for concept items (not for groups):

Add a concept group

A concept group is a concept that groups one or more child-concepts. To create a dataset group perform the following steps:

  • Click add, this will create a stub concept.

Add dataset concept button

  • Set the concept Type to Group

Set concept type to group

  • Type a name for the concept group in Name

When you have entered a name for the concept group, that name is now shown in the dataset tree on the left-hand side.

  • Multiple textfields can now be added to the concept group: Description, Relations, Source, Rationale, Properties, Operationalization, Comment.

Single-click on one of those field names to open or close a textbox editor where you can enter text. Add concept description

  • It is possible to move the concept in the dataset tree by selecting Move concept within dataset
  • Save the concept group by clicking Save

Save concept

Add a concept item

To create a dataset concept item perform the following steps:

  • Click add, this will create a stub concept.

En dataset add concept.png

  • Set the concept Type to Item

Set concept type to item

  • Type a name for the concept group in Name

When you have entered a name for the concept, that name is now shown in the dataset tree on the left-hand side.

  • Multiple textfields can now be added to the concept group: Description, Relations, Source, Rationale, Properties, Operationalization, Comment.

Single-click on one of those field names to open or close a textbox editor where you can enter text. Add concept description

  • It is possible to move the concept in the dataset tree by selecting Move concept within dataset
  • Save the concept by clicking Save

Save concept

Add a concept from a repository

When you add a concept group or concept item, ART-DECOR automatically searches all known repositories for similar concepts. Note that this is unrelated to which repository projects are configured in Projects / General / Repository reference.

Please note that:

  • When you want to add a concept from the repository, your own concept should either be a group, or item. And that should be the same as the original concept in the repository.
  • When adding concepts you can either add them:
    • As reference: Select this option if you want a singular reference to the concept. This will allow you to go to the referenced concept, without pulling physically pulling it into your current structure. This option is suited for circular references. You may convert a reference to an inherited structure at any time.
    • As inherit: Select this option if you want to copy the referenced structure into your current structure. Each concept will then point to its original for its properties (name, description, value domain etc.). This option is not suited for circular references. Your inherited structure will not automatically get new concepts if they are added in the original. You cannot convert an inherited structure into an reference.

Add concept translations

To add translations to your project, first make sure that:

Now we can add translations to dataset concepts with the Translate button on the dataset concept editor form:

Dataset concept translate.png

This will open a display for adding translations to the dataset concept. You can add translations for the various dataset concept fields: Name, Synonym, Description, Source, Rationale, Comment, Operationalization.

After adding translations, click Close to close the form. Dataset concept translate close.png

Next you need to click Save to save the translations:

Dataset concept translate save.png

Example dataset

Removing concepts

Moving concepts

Form parameters

The dataset form, as most other forms, supports parametrization.

/decor-datasets--[prefix]?id=[dataset id]&effectiveDate=[dataset effective date]&conceptId=[concept id]&conceptEffectiveDate=[concept effective date]
Parameter Description Since
prefix Project prefix always
id Switches to the project dataset with this id. Format: OID art v1.5
effectiveDate Switches to the project dataset with this effective date. Format: yyyy-mm-ddThh:mm:ss. Works only in combination with param id art v1.5
datasetId Switches to the project dataset with this id. Format: OID always (deprecated in art >= 1.5)
conceptId Switches to the project dataset concept with this id. Format: OID. If you do not specify params id/effectiveDate, then this param only works if the concept happens to be in the default/newest dataset always
conceptEffectiveDate Switches to the project dataset concept with this effective date. Format: yyyy-mm-ddThh:mm:ss. Works only in combination with param conceptId always

Locking

ART uses concept level locking to prevent multiple users form editing the same item. When a concept is edited this concept and all children of this concept are locked. Locks are released when the changes are saved or the action is cancelled, when navigating away from the page a warning is displayed:

Page-leave-message.png

Navigating away from the page without saving the changes or cancelling the edit will leave the lock in place. If the same user attempts to edit the item at a later time the lock will be cleared automatically, if another user attempts to edit the item a message is displayed that the item is locked:

Concept-locked-message.png

It is possible to break the lock at this time, be sure that no other user is actually working on this item before breaking a lock.

Project administrators can access an overview of all locks for the project on the Status tab of the Project Information page:

Project-locks.png

Individual locks can be cleared here and all locks for a particular user can also be cleared here.

The Status tab on the DECOR administration page shows the locks for all projects:

Decor-locks.png

Individual locks can be cleared here and all locks for a particular user can also be cleared here.