Skip to content

Latest commit

 

History

History
465 lines (292 loc) · 19.2 KB

User Guide.md

File metadata and controls

465 lines (292 loc) · 19.2 KB

National Data Dictionary User Guide

What is it for ?

The NSIP Team at ESA has developed a prototype online data dictionary service intended to make it easier to mobilise data between different agencies and vendors, in order to

  • make data collection more efficient for schools and vendors
  • coordinate the enterprise data modelling efforts of different school authorities
  • help agencies to plan data collection activities more effectively.

The definitions in the data dictionary will reflect a broad, national consensus, but individual standards and collections may involve different granularities or understandings of data, having been devised for different purposes. In order to reconcile the differences in definitions and usage between school authorities, the data dictionary definition will link to the different contexts that its elements turn up in, particularly in different data collections, and the different definitions and business rules applied in those contexts. For example, it should capture the different ways that authorities define schools and sub-school entities, as a caveat for people working across authorities.

The data dictionary can also be used to enable privacy compliance, by identifying sensitive data elements transacted between agencies, without restriction to a single data standard. Facilitating data privacy compliance is a downstream benefit of the data dictionary, and its use to that end will be piloted. However, privacy classifications of data are specific to agencies, and the data dictionary will not impose a single privacy classification over its data definitions.


Where is it ?

Home page: data-dictionary.net


PART 1 -- SignUp, Login, Reset Password

  • New User Registration

    Users can only be registered by National Data Dictionary administrators. Please Contact admin via email [email protected] for registration.

    After registration, an unique, unchangeable login user name and initial password will be sent through provided email. We strongly suggest that users reset their own password on subsequent login.

  • Reset Password

    Reset Password

    Reset Password

    Your current valid password must be provided to reset your password.

    Reset password rule: Passwords must be no less than 8 characters long, including at least one uppercase number, one numeric digit, and one symbol.

    (If the captcha is not easy for you to read, click on it to refresh for a new captcha.)

  • User Login

    Log In

    If you log in successfully, you will be redirected to the dictionary main page.

    (If the captcha is not easy for you to read, click on it to refresh for a new captcha.)

  • Forget Login Password

    Forget Password

    If you have forgotten your login password, please contact admin via email [email protected], and they will reset the password for you manually.

PART 2 -- Entity & Collection List & Their Content, Annotation.

  • User Name & Exit

    Current User

    Your current login user name and the exit button are located at the top-right of the screen.

    To log out, click the Exit button. A popup window will ask you to confirm logout.

    Logout window

    If logout is confirmed, the site will jump back to the login page.

  • Message Bar

    Message Bar

    A global message bar is located at the top-left of the screen.

    It shows basic messages relevant to the current tab, such as dictionary info, admin hints, a user list summary, etc.

  • Selection Tab

    Tab Selection

    A Tab Selection control is located at the top-right of the screen.

    There are 4 tabs available: Dictionary/Approval/Admin/Maintain. Only the Dictionary tab is accessible to normal users. The other 3 tabs are visible and available for site administrators.

    The Approval tab is invisible to site administrators, unless there are some pending submission candidates waiting for admin approval review.

  • Entity & Collections List

    Entity & Collections List

    The Entity and Collection list panel is located at the left side of the dictionary page. There is a 4-option radio button selection filter, to separate all items based on their metadata type. They can be selected by tabs.

    • Elements are attributes of Objects
    • Elements are concrete instances of Abstract Elements
    • Different Elements are collected in different Data Collections

    In terms of ISO 11179 (used e.g. in Aristotle),

    • Abstract Elements correspond to Properties
    • Elements correspond to Data Element Concepts
    • Data Elements are not currently modelled in the Data Dictionary: the interface provides information on values, but it does not currently model data domains

    For the entity list only, there is an additional filter with four selections (all/abstract/element/object) for its content, based on the entity's metadata type. The all selection means no filter for the entity list.

  • Entity Clickable For Hierarchy & Content Display

    e.g. If ACARA ID is selected on the left panel, the selected item name's font becomes bold and italic.

    Entity Click

    and the hierarchy and content for ACARA ID are shown on the right-hand panel.

    Entity Content

  • Collection Clickable For Content Display

    e.g. If Australian Government Address Collection is selected on the left panel, the selected item name's font becomes bold and italic.

    Collection Click

    and the content of Australian Government Address Collection is shown on the right-hand panel.

    Collection Content

  • Full Text Search

    The site supports search on the Entity panel

    Full Text Search

    e.g. entering school in the search panel will search for the text school in the text content of all items. After searching, only those items whose content includes the text school (case insensitive) are filtered and shown in the panel.

    If you want to reset the search results, i.e. list all items again, just clear the search input text area, and click the "search" button again.

  • Entity Hierarchy View & Jumping

    Elements and Objects are organised hierarchically in the Data Dictionary; for example,

    • Organisation > School > Campus (objects)
    • Person > Staff, Student (objects)
    • Identifier > Organisation Identifier > School Identifier (abstract elements)

    This hierarchical organisation is presented on the top-left:

    Entity Hierarchy

    Via the entity hierarchy, the ancestor, siblings & descendants of the current entity can be clicked and navigated.

    e.g. We selected School Identifier from the entity list, and its hierarchy path is automatically generated and shown as Identifier => Organisation Identifier => School Identifier. Meanwhile, the final entry of the listing provides a list of subclasses of the current entity, which are derived from School Identifier. All those path items are clickable for shortcut navigation.

  • Subscription

    Any item from the list panel can be subscribed/unsubscribed to.

    On the right bottom area of the page, you can subscribe or unsubscribe to the current entity by toggle clicking the round bookmark button

    Subscription Icon

    the current selected item is subscribed or unsubscribed.

    The subscribed items are marked in the left-hand entity list panel in green bold font style, and other entities are given are normal black font style.

    e.g.

    Subscription Style

    Once any of your subscribed items are updated, i.e updates are approved by the admin, your registered email will receive a notification of what changes have been made.

  • Dump Dictionary Data

    The entire backend dictionary data can be downloaded as a JSON package or a CSV single file.

    • The JSON package is the native data encoding of the data dictionary, and contains the full details of the site entries.
    • The CSV file is intended for import into Aristotle, and it contains a subset of the data compatible with Aristotle's ISO 11179 modelling of Data Element Concepts. (So it does not contain specifics such as legislation, business rules, or multiple definitions.)

    Export is done by by clicking the round data dump button on the right bottom area of the page.

    Dump Icon

    A selection window will pop up to let you choose which kind of dictionary data you want to download.

    Dump Choose Icon

    If you select JSON, the dumped file is a ZIP package including a JSON file for each entity (including objects and abstract elements), and a subfolder including a JSON file for each collection.

    If you select CSV, the dumped file is a single CSV file which inludes all Elements in the Data Dictionary, and related field data (references and comements), corresponding to ISO 11179 Data Element Concepts.

  • Comment Area

    For each selected entity or collection, any user can add comments.

    The comment Area is located at the right-bottom area of the page, and is highlighted in blue.

    Comment

    Each comment queue is specific to the current selected item. Comments are hosted locally using the ISSO commenting server, and commenters are identified by their optionally supplied name, e-mail, and/or website (as with Gravatar and Disqus); your supplied details are remembered as a cookie. Comments support basic Markdown markup; see https://isso-comments.de/docs/reference/markdown-config/[ISSO documentation for more detail].

PART 3 -- Create or Modify Entity & Collection

  • Create Entity or Collection Content

    If you wish to contribute to the dictionary, you can create a new entity or collection by clicking the round plus button

    New Icon

    After editing, the new entry will be submitted to the approval candidate list. It will only appear on the website once an admin has approved it.

    From the left list panel, if the current selected tab option is an entity (i.e. an Element, Abstract Element, or Object), clicking the round plus button will jump into the New Entity Page. (You will be able to pick later whether the new entity is an Element, Abstract Element, or Object.)

    If the current selected list tab option is collection, clicking the round plus button will jump into the New Collection Page.

    So once you click this icon, you will be redirected to the relevant content entry/edit page.

    The entity entry/edit area is located on the left-hand panel of this page, and looks like:

    New Entity Page

    There are multiple groupings of content fields (Entity, Definition, SIF, OtherStandards, LegalDefinitions, Sensitivity, Collections, Metadata), divided by top tabs. Select a different tab to write/edit its fields.

    The content preview area is located in the right-hand panel of the page, and consists of two preview styles: visual effect and raw json. The preview style can be selected by a tab at the top of the screen.

    This is a preview-only panel: the actual content is edited on the left-hand panel, and the right-hand panel is updated in real time as you type.

    The content under the visual effect tab looks like how the entity will look in the site once accepted:

    New Entity Page

    The content under the raw json tab looks like how the data will be exported to JSON (and how it is internally represented); it is a developer view of the content:

    New Entity Page

    Once you have finished your new entity/collection input, click the tick round button

    Submit Icon

    This will submit your new entry into the approval list, to await admin review.

    After submission, your page will auto-redirect to the previous List Content Page

  • Exit Creating Page

    If you want to discard your entry and jump back, click the exit round button

    Discard Icon

    Your page will auto-redirect to the previous List Content Page.

  • Edit Existing Entity or Collection Content

    If you wish to modify existing dictionary data, you can edit an existing entity or collection by clicking the round pen button

    Edit Icon

    This will submit your updated content to the approval candidate list for review.

    From your left list panel, if the current selected tab option is an entity, clicking the round pen button' will jump into the Edit Entity Page.

    If the current selected list tab option is collection, clicking the round pen button will jump into the Edit Collection Page.

    Once you click this icon, you will be redirected to the relevant content edit page. This edit page is the same form as the new entry page, but it has prefilled content based on the existing data held for the entity in the dictionary.

    The Functionality of Edit Page is the same as those of New Page. The only difference is that in Edit Page, there are prefilled available values in each input area.

  • Exit Edit Page

    If you want to discard your entry and want to jump back, click the exit round button

    Discard Icon

    Your page will auto redirect to the previous List Content Page.

  • Update Existing Entity or Collection Name

    The unique name of an existing item can also be changed. Because of how data dependencies work for the dictionary, this is available through a different interface. To change the unique name of an existing item, click the rectangular pen button located at the right side of the Name: (name-value) row

    Change Name Icon

    When you do, a input box appears as below:

    Change Name Icon

    If the new input name is accepted as unique, a new candidate submission will be added to the approval list. Once the submission is approved by admin, then the original item name wil be updated in the dictionary.


For Administrator:

Apart from all Dictionary tab functionality provided to normal users, administrators are also provided 3 additional functionalities of Approval, Admin and Maintain.

If you are logged in with an admin role, on the top right area of the Dictionary Page, you will see those three specific options.

Admin Options

[Approval]:

Under this option, new or edited submission items are listed on the left-hand side. These items are clickable and once clicked, their content is displayed on the right-hand panel. e.g. :

Submission Item

At the right bottom area of the page, there is an approval button.

Submit Icon

If clicked, the selected submitted item will be approved by current logged in administrator, and the content will be added to the dictionary, available for viewing by all logged in users.

The approved item will therefore disappear from the candidate list in Approval page, and will appear in the left-hand panel of the Dictionary page.

Meanwhile, if a new item is approved, every registered user will receive a notification email saying: "new item [MyTest] has been added into data dictionary".

If an update to an existing item is approved, all users subscribed to it will receive a notification email saying "data dictionary item [MyTest] has been updated".

[Admin]:

Under this option, registered users are shown in a table, as below:

Admin Options table

[user name], [user email], [admin status], [online status] and [active status] are displayed on this table.

Each table row is clickable. E.g. if the row for user 'cdutwhu' is clicked, a popup window is displayed, and some user settings can be made from that window:

Admin Options Edit

If an user's admin status is false, then this user cannot do approval or user admin.

If an user's active status is false, then this user cannot log in to the National Data Dictionary.

If an user's delete status is true, then after confirmation, this user will be deleted permanently from the National Data Dictionary.

The user's password can also be reset by admin here. Just set a new valid password for the current selected user.

[Maintain]

Under this option, there are three system backend dictionary data maintenance functions.

  1. restore from JSON package

Restore Options Edit

Clicking this button, a file select dialog will pop up to select a package including multiple (entity/collection)JSON files. This package (which will have been exported as a data dump) is used to restore the whole backend dictionary data.

If the uploaded package is determined to be valid for restoring, the whole backend dictionary data will be updated, overwriting any existing data; and any pending submission data will be removed.

  1. backend data validation

Restore Options Edit

Clicking this button will do a backend dictionary data validation. A message window will pop up letting you know the details of errors for different entities. These errors are mostly to do with referential integrity (broken links between entities, e.g. Element belonging to a collection that no longer exists), and valid entity hierarchies as expected by ISO 11179; e.g. all Elements (ISO 11179 Data Element Concepts) should be instances of an Abstract Element (ISO 11179 Property), and attributes of an Object (ISO 11179 Object Class).

  1. restructure whole backend data

Restore Options Edit

Clicking this button makes the backend service do a whole data restructure, and is needed periodically as the data is restructed, to ensure accurate select menu contents and data export. This includes reformulating the hierarchy for each entity's super class, re-assigning each entity's internal ID, and recomputing each entity's related cross reference entities.