Difference between revisions of "ART Project Editor"

(added a __TOC__)
(Reference a building block repository)
(27 intermediate revisions by 4 users not shown)
Line 1: Line 1:
 
__TOC__
 
__TOC__
==External services==
+
=External services=
 
The external services that can be configured on the project-tab:
 
The external services that can be configured on the project-tab:
 
* The ART-DECOR Automatic Notifier System ([[ADANS]])
 
* The ART-DECOR Automatic Notifier System ([[ADANS]])
==Reference a building block repository==
+
=Add a language to a project=
 +
If you want to add a language to a project, you can perform the following steps:
 +
Open '''Project'''-tab, section: '''general'''
 +
 
 +
Edit the name for the project.
 +
[[File:En_language_add_01.jpg|750px]]
 +
 
 +
Click on the plus to add a language:
 +
 
 +
[[File:En_language_add_02.jpg|500px]]
 +
 
 +
Enter a new language in the first field, for instance: en-US
 +
 
 +
Add an English name for the project.
 +
 
 +
To save, click on the button: '''Change'''
 +
[[File:En_language_add_03.jpg|500px]]
 +
 
 +
Save the updated project settings by clicking '''Save''':
 +
 
 +
[[File:Save_form.png|150px]]
 +
 
 +
Select the added language in the top-right:
 +
[[File:En_language_add_05.jpg|750px]]
 +
The project name should now be shown in English.
 +
[[File:En_language_add_06.jpg|500px]]
 +
 
 +
After adding a translation for the project name, this will enable you to add translations to dataset concepts, see [[ART_Dataset_Editor#Add_concept_translations|Dataset Editor documentation]].
 +
 
 +
=Marking a project as building block repository=
 +
In the project-tab, projects can be marked as building block repository (BBR). In that way they are marked as containing reusable content. Content from BBR's can be reused in other projects.
 +
 
 +
Follow these steps to mark a project as BBR:
 +
* Log in as '''decor-admin'''
 +
* Go to tab '''Project/General'''
 +
* Click on '''Contains reusable content?'''
 +
[[File:mark_repository.png|750px]]
 +
 
 +
* Click '''Save''' to update the project information
 +
 +
=Reference a building block repository=
 
In order to use concepts, value sets, and templates from a BBR (building block repository), it is necessary to first add a reference to a repository. Follow these steps to add a reference to a BBR from a project:
 
In order to use concepts, value sets, and templates from a BBR (building block repository), it is necessary to first add a reference to a repository. Follow these steps to add a reference to a BBR from a project:
 +
* If not done yet: First mark the project containing reusable content as BBR, see [[ART_Project_Editor#Marking_a_project_as_building_block_repository]]
 
* Log in as '''decor-admin'''
 
* Log in as '''decor-admin'''
 
* Go to tab '''Project/General'''
 
* Go to tab '''Project/General'''
Line 16: Line 57:
 
[[File:En_project_bbr_reference_added.png|750px]]
 
[[File:En_project_bbr_reference_added.png|750px]]
 
* After adding the BBR-reference: when adding dataset concepts, value sets or templates, content from the BBR is also presented in the current project
 
* After adding the BBR-reference: when adding dataset concepts, value sets or templates, content from the BBR is also presented in the current project
==Adding authors to a project==
+
 
 +
=Adding authors to a project=
 
Before a user can edit a project, the following steps must be performed:
 
Before a user can edit a project, the following steps must be performed:
 
* the user must have a personal ART-DECOR user account, please [[Contact]] us to obtain one
 
* the user must have a personal ART-DECOR user account, please [[Contact]] us to obtain one
Line 27: Line 69:
 
** Click '''Add'''
 
** Click '''Add'''
 
** Click '''Save''' to update the project information
 
** Click '''Save''' to update the project information
 +
 +
=Project specific author settings=
 +
Any ART-DECOR user may be active in multiple projects. He may be acting from different organizations depending on the project, and he may be more or (temporarily) less involved. For these reasons ART-DECOR supports switching on/off notification settings for [[ADANS]] on a project specific level.
 +
Any user with 'decor-admin' rights in the project can adjust the settings for any project author. In addition to that, the decor-admin project user may switch the ADANS notifier on/off for the entire project. All other project (issue) authors can adjust their own settings.
 +
 +
The notifiers work as follows:
 +
* project notifier is on when it is '---' or 'on'. project notifier is off when it is 'off' (project opt-out)
 +
* user notifier is on when it is 'on'. project notifier is off when it is '---' or 'off' (user opt-in)
 +
 +
[[File:project-author-decor-view.png|750px|normal user view]]
 +
 +
[[File:project-author-decor-admin-view.png|750px|decor-admin user view]]
 +
 +
=Preflighting publication and quality checks=
 +
A number of checks can be done to check the quality of your project before you create a publication.
 +
 +
1) Is the project schema and schematron valid?
 +
In order to check this:
 +
* Log in as '''decor-admin'''
 +
* Go to the page 'Project/Development'
 +
[[File:en_development_check_01.png|350px|Click Development page]]
 +
* Make sure the correct dataset is selected
 +
[[File:en_development_check_02.png|350px|Select dataset]]
 +
* Click the button to Check DECOR
 +
[[File:en_development_check_03.png|350px|Click Check DECOR]]
 +
 +
2) Consider making dynamic template and value set links static.
 +
In a final release you would not expect any dynamic template links.
 +
In a final release you may expect dynamic value set links, although they are likely the exception.
 +
 +
3) Run a [[TerminologyReport]] to check the quality of terminology content contained in the project.
 +
 +
4) Run development builds to test compilation and schematron validation against samples until you are satisfied that no valid things are marked invalid and vice versa.
 +
Possible parameters are:
 +
* Compile with '''Schematron closed'''
 +
[[File:en_development_check_04.png|650px|Compile a development version]]
 +
 +
After compiling you can validate XML instances from your desktop against the compiled schematron:
 +
[[File:en_development_check_05.png|650px|Validate XML instance]]
 +
 +
=Creating a new version / release / publication request=
 +
ART supports the creation of a project publication. For the publication feature to work, [[ADRAM|ADRAM]] needs to be installed and configured for this project.
 +
The creation of a version/release works as follows:
 +
* Log in as '''decor-admin'''
 +
* Check that ADRAM is configured for this project. On the tab 'Project/General', Publication location should contain a URL where the publication is going to be published. Behind the 'Publication location' it should show 'Release and Archive Manager configured' (this checks that ADRAM is configured for this project at the publication location).
 +
[[File:En project publication 01.jpg|750px|normal user view]]
 +
 +
On the tab 'Project/Version information', one can create a new version/release/publication request by clicking on the plus button (see 1 at figure below). In addition the publication parameters and filter can be set by clicking on the wheel button (2). Finally you may compare two releases of your project by clicking on the delta button (3).
 +
[[File:Projectpublication02.png|750px|normal user view]]
 +
 +
When clicking on the plus button, a dialog is presented where information detailing the version/release/publication request can be entered:
 +
* Description: enter a text describing the version or release.
 +
* Type: Intermediate version, or Release. For a release a release label can be entered.
 +
* Save compilations in the following languages: languages can be de-selected to exclude them from the publication.
 +
* Publication request: selecting this checkbox will trigger ADRAM to create a publication at the publication location shown.
 +
* Select 'Add' to confirm.
 +
[[File:En project publication 03.jpg|750px|normal user view]]
 +
 +
The wheel button presents a small dialog to change and maintain the publication parameters. It is organised in a few tabs (see 1 at figure below) ''General'', ''ISO schematron generation'', ''Human readable publication'' and Publication ''Filter'' and a cancel and save button below (2).
 +
[[File:Projectpublication10.png|550px|normal user view]]
 +
 +
The parameters can be switched on or off, a description is shown to explain what the parameter is for. In the ''Human readable publication'' tab there is also a small lists of artefact categories to be chosen from to determine whether they are included in a resulting PDF or not (1).
 +
[[File:Projectpublication11.png|550px|normal user view]]
 +
 +
The Publication ''Filter'' tab allows to set filters on and off, i.e. whether a publication contains all scenarios/transactions of the project (filter "off", see 1) or only selected ones. You can select either one or multiple scenarios/transactions from your project's scenarios/transactions in the list (2). You must give a label to your filter in order to describe the nature of the partial publication (3). The "Select all" and "Clear selection" button allows you to select all or none of the scenarios/transactions (4).
 +
[[File:Projectpublication12.png|550px|normal user view]]
 +
 +
The following different kinds of a publication status are supported:
 +
*When a publication request is first released by ADRAM and appears on the HTML landing page, its status is '''Under pre-publication review'''. The publication may be moved from that status to any of the following statuses.
 +
*'''Draft''': The publication is in draft, not yet finalized (nascent) and may be overridden at any time by a new and final release.
 +
*'''Active''': The publication is final (active) and can be considered for production use.
 +
*'''Retired''' The publication is considered to be no longer used.
 +
*'''Cancelled''': A publication has withdrawn, has never been used.
 +
*'''Build failed''': This special status represents that during the build and compile phase of the publication, ADRAM detected a processing error.
 +
 +
 +
ADRAM will check periodically for new publication requests and will create the publication at the publication location. Typically a review should be done after which the publication status can be upgraded to 'Draft/Active/Retired/Cancelled' via the tab 'Project/ Versions/Releases'. The status for a publication can now be updated in the column 'Edit':
 +
[[File:En project publication 05.jpg|750px|normal user view]]
 +
 +
ADRAM will re-check and update the publication status at the publication location. Visit the publication location URL to see the various releases:
 +
[[File:En project publication 04.jpg|750px|normal user view]]
 +
 +
=Maintaining a local OID Registry=
 +
ART-DECOR has a central place for registration of OIDs but you can certainly have your own local registrations. This is useful for example when your project contain references to code systems not maintained in ART-DECOR, nor administered in one of the hosted central OID Registries. Please note that centralized registration is usually to be preferred.
 +
 +
To view the local ids, you don't need to login. To update them you need to have decor-admin privileges and be author in the project. In both cases, go to the Ids tab on the Project form.
 +
 +
The Ids tab is divided in two sections "External Ids" and "Base Ids". The ''External Ids'' is meant for OID, defined and potentially registered outside the project, and used in the project. The External Ids may be of any type like Identifiers, Identification systems, Code systems etc. The ''Base Ids'' are used as an Identification system for the identification of various DECOR project artifacts and are normally derived from the project id.
 +
 +
Add a new id in either section using the appropriate <nowiki>[</nowiki>+<nowiki>]</nowiki> button. Update a description by updating the appropriate fields. Don't forget to Save.
 +
 +
The base ids also sport the option "Default". When you have multiple base ids for a specific type, you may switch the default base id. Switching the default means that new artifacts of that type will be created using this new default unless you override.
 +
 +
[[File:En_project_ids_01.png|750px|project ids]]
 +
 +
=Form parameters=
 +
The project form, as most other forms, supports parametrization.
 +
 +
<syntaxhighlight lang="text">
 +
/decor-project--[prefix]?section=[section name]
 +
</syntaxhighlight>
 +
 +
{| style="text-align: left;" class="artdecorwiki"
 +
! Parameter !! Description !! Since
 +
|-
 +
| prefix || Project prefix || ''always''
 +
|-
 +
| section
 +
| Switches to the requested section. Options
 +
* general (default) - switches to the tab General
 +
* copyright - switches to the tab Copyright/Contributors
 +
* authors - switches to the tab Authors
 +
* versions - switches to the tab Versions
 +
* ids - switches to the tab Ids (admin only)
 +
* status - switches to the tab Status (admin only)
 +
* maintenance - switches to the tab Maintenance (admin only)
 +
* governancegroups - switches to the tab Governance groups
 +
| art v1.5.3
 +
|-
 +
| language
 +
| Displays contents in the requested language. When contents are not available in the requested language, there will be nothing to display. Example en-US, or nl-NL.
 +
| art v1.8.51
 +
|}

Revision as of 08:21, 11 September 2019

External services

The external services that can be configured on the project-tab:

  • The ART-DECOR Automatic Notifier System (ADANS)

Add a language to a project

If you want to add a language to a project, you can perform the following steps: Open Project-tab, section: general

Edit the name for the project. En language add 01.jpg

Click on the plus to add a language:

Error creating thumbnail: Unable to save thumbnail to destination

Enter a new language in the first field, for instance: en-US

Add an English name for the project.

To save, click on the button: Change

Error creating thumbnail: Unable to save thumbnail to destination

Save the updated project settings by clicking Save:

Save form.png

Select the added language in the top-right: En language add 05.jpg The project name should now be shown in English.

Error creating thumbnail: Unable to save thumbnail to destination

After adding a translation for the project name, this will enable you to add translations to dataset concepts, see Dataset Editor documentation.

Marking a project as building block repository

In the project-tab, projects can be marked as building block repository (BBR). In that way they are marked as containing reusable content. Content from BBR's can be reused in other projects.

Follow these steps to mark a project as BBR:

  • Log in as decor-admin
  • Go to tab Project/General
  • Click on Contains reusable content?

Mark repository.png

  • Click Save to update the project information

Reference a building block repository

In order to use concepts, value sets, and templates from a BBR (building block repository), it is necessary to first add a reference to a repository. Follow these steps to add a reference to a BBR from a project:

  • If not done yet: First mark the project containing reusable content as BBR, see ART_Project_Editor#Marking_a_project_as_building_block_repository
  • Log in as decor-admin
  • Go to tab Project/General
  • Click on Add building block repository. This will show a list of BBR's (depending on the server settings, these can include BBR's that reside on this server and/or BBR's that reside on external servers. See also the ART maintenance manual).
  • Select a BBR
  • Click add to add a BBR-reference in the current project

Screenshot that shows the user-interface for adding a BBR-reference from a project: En project bbr reference.png

  • Click Save to update the project information
  • After saving the project information, the BBR-reference is shown like:

En project bbr reference added.png

  • After adding the BBR-reference: when adding dataset concepts, value sets or templates, content from the BBR is also presented in the current project

Adding authors to a project

Before a user can edit a project, the following steps must be performed:

  • the user must have a personal ART-DECOR user account, please Contact us to obtain one
  • the user must have the proper group permissions (See also the ART maintenance manual)
  • Now the user can be added to the project by a decor-admin from the project:
    • Log in as decor-admin
    • Go to tab Project/Authors
    • Add a user to the current project by clicking Add author
    • Select the user
    • Click Add
    • Click Save to update the project information

Project specific author settings

Any ART-DECOR user may be active in multiple projects. He may be acting from different organizations depending on the project, and he may be more or (temporarily) less involved. For these reasons ART-DECOR supports switching on/off notification settings for ADANS on a project specific level. Any user with 'decor-admin' rights in the project can adjust the settings for any project author. In addition to that, the decor-admin project user may switch the ADANS notifier on/off for the entire project. All other project (issue) authors can adjust their own settings.

The notifiers work as follows:

  • project notifier is on when it is '---' or 'on'. project notifier is off when it is 'off' (project opt-out)
  • user notifier is on when it is 'on'. project notifier is off when it is '---' or 'off' (user opt-in)

normal user view

decor-admin user view

Preflighting publication and quality checks

A number of checks can be done to check the quality of your project before you create a publication.

1) Is the project schema and schematron valid? In order to check this:

  • Log in as decor-admin
  • Go to the page 'Project/Development'

Click Development page

  • Make sure the correct dataset is selected

Select dataset

  • Click the button to Check DECOR

Click Check DECOR

2) Consider making dynamic template and value set links static. In a final release you would not expect any dynamic template links. In a final release you may expect dynamic value set links, although they are likely the exception.

3) Run a TerminologyReport to check the quality of terminology content contained in the project.

4) Run development builds to test compilation and schematron validation against samples until you are satisfied that no valid things are marked invalid and vice versa. Possible parameters are:

  • Compile with Schematron closed

Compile a development version

After compiling you can validate XML instances from your desktop against the compiled schematron: Validate XML instance

Creating a new version / release / publication request

ART supports the creation of a project publication. For the publication feature to work, ADRAM needs to be installed and configured for this project. The creation of a version/release works as follows:

  • Log in as decor-admin
  • Check that ADRAM is configured for this project. On the tab 'Project/General', Publication location should contain a URL where the publication is going to be published. Behind the 'Publication location' it should show 'Release and Archive Manager configured' (this checks that ADRAM is configured for this project at the publication location).

normal user view

On the tab 'Project/Version information', one can create a new version/release/publication request by clicking on the plus button (see 1 at figure below). In addition the publication parameters and filter can be set by clicking on the wheel button (2). Finally you may compare two releases of your project by clicking on the delta button (3). normal user view

When clicking on the plus button, a dialog is presented where information detailing the version/release/publication request can be entered:

  • Description: enter a text describing the version or release.
  • Type: Intermediate version, or Release. For a release a release label can be entered.
  • Save compilations in the following languages: languages can be de-selected to exclude them from the publication.
  • Publication request: selecting this checkbox will trigger ADRAM to create a publication at the publication location shown.
  • Select 'Add' to confirm.
Error creating thumbnail: Unable to save thumbnail to destination

The wheel button presents a small dialog to change and maintain the publication parameters. It is organised in a few tabs (see 1 at figure below) General, ISO schematron generation, Human readable publication and Publication Filter and a cancel and save button below (2). normal user view

The parameters can be switched on or off, a description is shown to explain what the parameter is for. In the Human readable publication tab there is also a small lists of artefact categories to be chosen from to determine whether they are included in a resulting PDF or not (1). normal user view

The Publication Filter tab allows to set filters on and off, i.e. whether a publication contains all scenarios/transactions of the project (filter "off", see 1) or only selected ones. You can select either one or multiple scenarios/transactions from your project's scenarios/transactions in the list (2). You must give a label to your filter in order to describe the nature of the partial publication (3). The "Select all" and "Clear selection" button allows you to select all or none of the scenarios/transactions (4). normal user view

The following different kinds of a publication status are supported:

  • When a publication request is first released by ADRAM and appears on the HTML landing page, its status is Under pre-publication review. The publication may be moved from that status to any of the following statuses.
  • Draft: The publication is in draft, not yet finalized (nascent) and may be overridden at any time by a new and final release.
  • Active: The publication is final (active) and can be considered for production use.
  • Retired The publication is considered to be no longer used.
  • Cancelled: A publication has withdrawn, has never been used.
  • Build failed: This special status represents that during the build and compile phase of the publication, ADRAM detected a processing error.


ADRAM will check periodically for new publication requests and will create the publication at the publication location. Typically a review should be done after which the publication status can be upgraded to 'Draft/Active/Retired/Cancelled' via the tab 'Project/ Versions/Releases'. The status for a publication can now be updated in the column 'Edit': normal user view

ADRAM will re-check and update the publication status at the publication location. Visit the publication location URL to see the various releases: normal user view

Maintaining a local OID Registry

ART-DECOR has a central place for registration of OIDs but you can certainly have your own local registrations. This is useful for example when your project contain references to code systems not maintained in ART-DECOR, nor administered in one of the hosted central OID Registries. Please note that centralized registration is usually to be preferred.

To view the local ids, you don't need to login. To update them you need to have decor-admin privileges and be author in the project. In both cases, go to the Ids tab on the Project form.

The Ids tab is divided in two sections "External Ids" and "Base Ids". The External Ids is meant for OID, defined and potentially registered outside the project, and used in the project. The External Ids may be of any type like Identifiers, Identification systems, Code systems etc. The Base Ids are used as an Identification system for the identification of various DECOR project artifacts and are normally derived from the project id.

Add a new id in either section using the appropriate [+] button. Update a description by updating the appropriate fields. Don't forget to Save.

The base ids also sport the option "Default". When you have multiple base ids for a specific type, you may switch the default base id. Switching the default means that new artifacts of that type will be created using this new default unless you override.

project ids

Form parameters

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

/decor-project--[prefix]?section=[section name]
Parameter Description Since
prefix Project prefix always
section Switches to the requested section. Options
  • general (default) - switches to the tab General
  • copyright - switches to the tab Copyright/Contributors
  • authors - switches to the tab Authors
  • versions - switches to the tab Versions
  • ids - switches to the tab Ids (admin only)
  • status - switches to the tab Status (admin only)
  • maintenance - switches to the tab Maintenance (admin only)
  • governancegroups - switches to the tab Governance groups
art v1.5.3
language Displays contents in the requested language. When contents are not available in the requested language, there will be nothing to display. Example en-US, or nl-NL. art v1.8.51