{% extends "page.html" %} {% block subtitle %}{{ _("Etsin instructions") }}{% endblock %} {% block breadcrumb_content %}
  • {{ h.nav_link(_('Help'), controller='ckanext.kata.controllers:KataInfoController', action='render_help', highlight_actions = 'new index') }}
  • {% endblock %} {% block primary_content %}

    {{ _('General information') }}

    {{ _('This help page will guide you through the most common tasks in Etsin. Use the links on the left side of the page to quickly navigate to the desired section.') }}

    {{ _('Also, have a look at the FAQ page. It might give you an answer to a specific question in mind.') }}

    {{ _('Common phrases') }}

    • {{ _('Dataset: a single set of metadata (of data)') }}

    {{ _('Search (Datasets)') }}

    {{ _('Search can be accessed from the Datasets page. You can submit your queries using the Search tab or the Advanced search tab, which will provide a guided interface for more complex queries. Note that you can also provide more complex queries to the search field by providing a correct syntax, which will be discussed later in this section.') }}

    {{ _('Limiting the search with facets') }}

    {{ _('The right side of the search page provides facets from different categories. You can choose multiple and from different categories with a mouse click. You can remove a facet selection by pressing the "x" button. For example choosing free licenses from the License facet selection would search through the free data.') }}

    {{ _('Using advanced search') }}

    {{ _('Advanced search feature makes it easy for you to construct more complex searches. You can add as many search criteria as you want from the "ADD" button: Choose the desired target field from the menu and add logical operators from the leftmost menu. Note that the AND operators are grouped together so that they will take precedence over criteria bound by OR.') }}

    {{ _('Wildcards') }}

    {{ _('The searches support two different wildcard characters. Symbol "?" provides a single character wildcard search. The following search would match both "text" and "test": ') }}

    {{ _('te?t') }}

    {{ _('To match multiple characters you can use the symbol "*". It matches 0 or more characters and can be placed in the middle of the term as well as the end: ') }}

    {{ _('test*') }}
    {{ _('te*t') }}

    {{ _('Logical operators and grouping') }}

    {{ _('The search engine used by Etsin supports the boolean operators AND, "+", OR, NOT and "-". Note that the boolean operators must be provided as upper case characters. To search datasets containing both "climate" and "rain" you would type: ') }}

    {{ _('climate AND rain') }}

    {{ _('To search for datasets that must contain climate and may also contain rain the search would be: ') }}

    {{ _('+climate rain') }}

    {{ _('NOT and "-" work similarly. These can be used to rule out words. For example, to search for datasets containing "climate" but not the word "rain" you would search for: ') }}

    {{ _('climate NOT rain') }}

    {{ _('If needed, you can group the search criteria with parentheses. This will enable sub queries. For example, to search for either "sun" or "rain" and "climate", use query: ') }}

    {{ _('(sun OR rain) AND climate') }}

    {{ _('Fuzzy Searches') }}

    {{ _('With fuzzy search you can match a word that is similar to the given one. Fuzzy search is constructed with symbol "~". To search spellings similar to "roam" you could make a search: ') }}

    {{ _('roam~') }}

    {{ _('Range Searches') }}

    {{ _('The range searches work for both date fields and non-date fields. You can search for datasets added between the lower and upper bounds of the provided dates with: ') }}

    {{ _('version:[20131212 TO 20141212]') }}

    {{ _('Boosting a term') }}

    {{ _('You can raise any word\'s importance by boosting it with the symbol "^" and a number. The number is so called boost factor and the higher the number is, the more relevant the word will be. For example, to search for terms "northern hemisphere" and "southern hemisphere" with the "northern hemisphere" wanted to be more relevant, you could construct a search like: ') }}

    {{ _('"northern hemisphere"^5 "southern hemisphere"') }}

    {{ _('Dataset') }}

    {{ _('Choosing a dataset from the search result will show the dataset\'s information. The dataset page also provides additional features:') }}

    • {{ _('If you have sufficient privileges, you can choose to edit the metadata of the dataset.') }}
    • {{ _('If you don\'t have enough privileges but you are logged in, you can request for edit rights.') }}
    • {{ _('From the tabs you can see dataset\'s past activities and followers.') }}
    • {{ _('In the related tab you can see publications and datasets related to the dataset in question and if you are logged in you can add a relation to this dataset.') }}
    • {#
    • {{ _('In the right hand navigation you can choose to export the dataset\'s basic metadata in RDF format from the "RDF" link.') }}
    • #}
    • {{ _('If you are logged in, you can choose to follow the dataset. By following the dataset you would start to receive changes to this data to your Dashboard\'s news feed.') }}

    {{ _('Add Dataset') }}

    {{ _('If you are logged in you will find "Add Dataset" button for example from the Datasets and Dashboard pages. This button brings you to the Add Dataset form. The Add Dataset page encourages and guides you to fill in the metadata as well as possible to ensure that metadata is of good quality and your data is as well described as possible. The fields are accompanied with a tooltip, "?", which will give instructions for that specific field.') }}

    {{ _('Required information') }}

    {{ _('The upper part of the page mostly contains the data fields that are the compulsory minimum for every dataset. Language and project information can be skipped by checking the checkbox in the section in question. The fields are shortly explained here, the popup marked with \'?\' sign will provide more information on add dataset page.') }}

    {{ _('Basic information about the dataset:') }}

    {{ _('Titles: Title and its language. Multiple titles with different languages can be given.') }}
    {{ _('Authors: Author and author\'s organisation. Multiple author/organisation pairs can be given.') }}
    {{ _('Contributors: Contributor and contributors\'s organisation. Multiple author/organisation pairs can be given.') }}
    {{ _('Keywords: Keywords use KOKO ontology from http://finto.fi/. The keywords are chosen from suggestions or you can also provide your own word if suitable is not available.') }}
    {{ _('Languages: List of languages the data contains, in ISO 639-3 format. If there is no language, you can check the checkbox.') }}
    {{ _('Distributor: Provide a name, phone number, valid email address and a homepage so that others can contact the distributor about the data. This can be you as well. The email address will be hidden from others than dataset editors and a messaging tool is provided for others instead.') }}

    {{ _('Agents and roles:') }}

    {{ _('Project that produced this dataset: This information can be skipped by checking the checkbox. If the information is given, all four fields must be filled with project data: Project name, project\'s funder, funding id (will be hidden to non-editors) and project\'s homepage.') }}
    {{ _('Owner information: Data\'s owner\'s information, for example a name or an identification URL.') }}

    {{ _('Identification information of data:') }}

    {{ _('Permanent identifier: The permanent identifier is the data\'s unique identifier. If none is provided, Etsin will give it an URN identifier from the address space of the National Library of Finland, from a subspace given to Etsin. This field can NOT be changed afterwards.') }}
    {{ _('Version identifier: The version PID can be given or if left empty is generated by Etsin. Automatically generated identifiers will be URNs from the address space of the National Library of Finland, from a subspace given to Etsin.') }}
    {{ _('Modification date: Choose a modification date from the calendar tool. The default value is this moment.') }}

    {{ _('Usage information tells where the data is located and/or how it can be accessed:') }}

    {{ _('Dataset is available for use: Choose a suitable option for your data. Provide also the URL\'s required, the URL fields are displayed according to your choice. No URL is asked for if you choose the option "only by contacting the distributor".') }}
    {{ _('License: Choose a license from the popup menu. This will define who can use your data and possibly how they can use it.') }}

    {{ _('Recommended information') }}

    {{ _('Beneath the required information are the recommended data fields that are by default hidden but can be toggled visible. It is useful to describe your data as well as possible, so if the fields in recommended information are valid to your data, please fill them. Here are short explanations of the fields:') }}

    {{ _('Coverage provides fields for spatial and temporal coverage:') }}

    {{ _('Spatial coverage: Location names are retrieved the location name database at http://finto.fi/. Choose the locations covered in your data from the suggestions. You can also add your own location by typing and accepting it.') }}
    {{ _('Temporal coverage: Choose a time period covered in your data using the date selector.') }}

    {{ _('Relations:') }}

    {{ _('Discipline/branch of science: The disciplines are chosen from the OKM-TIETEENALA ontology, from http://finto.fi/. The disciplines are provided only in Finnish and you should use these Finnish versions to help grouping and searching of the data.') }}

    {{ _('File information is especially technical information about your data:') }}

    {{ _('MIME type: The mimetype of the file, see http://www.iana.org/assignments/media-types for a complete list.') }}
    {{ _('Checksum and Algorithm: Checksum and the algorithm it was taken with, especially to verify that the file has not changed.') }}

    {{ _('Dataset lifecycle events:') }}

    {{ _('In case there are events in this dataset, fill all four (event, by whom, when, description) fields. Choose the event type from the list and provide who did the act. Add also the time in format "1111-11-11T11:11:11" and a description. Multiple events can be added, but all four are required when adding one.') }}

    {{ _('Free description:') }}

    {{ _('Description: The description field can contain almost anything. Note, that the contents of the description field are visible in the search results, so giving a good description may bring more attention to your dataset.') }}

    {{ _('Additional features') }}

    {{ _('Etsin contains several other features which are shortly covered here.') }}

    {{ _('User profile') }}

    {{ _('User profile provides basic information about you, your dataset and actions. The user profile can be accessed from the upper right corner. The upper right corner also provides a direct link to your own datasets. Note that if you have logged in using Haka, you can not change your profile information from Etsin: the changes must be done by your home organisation.') }}

    {{ _('Stats') }}

    {{ _('The Stats link will take you to the statistics page. The page will show you some general information about Etsin, its datasets and users.') }}

    {{ _('REMS') }}

    {{ _('Etsin is integrated to a REMS service, Reetta. This means that you can define your data to be accessible only after an application form is filled and sent to you to accept in the REMS service. You can create your own workflow or use the automatically generated simple form. When a REMS application is done user can go to fill the application from the download link of the data. Read more from: ') }} {{ _('REMS manual') }}

    {#

    {{ _('Collections') }}

    {{ _('The Collections page shows categories which may have datasets under them, grouped together under one set. You can also add a new collection and from the collection page also add a dataset under this collection. Note, that for now only collections\' administrators can add datasets under it.') }}

    #}

    {{ _('Dataset administration') }}

    {{ _('From the dataset view page you can choose a link to administer dataset rights if you have sufficient privileges to do so. From the administration page, you can add editors and admins (if you have admin privileges) for the dataset. Type and accept the username with enter or mouse click in the "User" field, choose a role from "Role" menu and press "Add". If you don\'t find the user, he or she probably hasn\'t logged in to Etsin yet. In this case you can send an email with your own message added to it. The message is not obligatory. Note, that for spam protection you must also fill the CAPTCHA field. If the displayed words are too messy, you can reload the CAPTCHA to get a new string from its reload button.') }}

    {{ _('From the top of the page, from the member list table, you can remove users from their roles in this dataset. Note, that you can not remove the built-in user accounts, like visitor and logged_in, nor yourself.') }}

    {{ _('Metadata supplements') }}

    {{ _('If you have additional documents that describe your data beyond required and recommended fields, you can provide such extra information in metadata supplements. An example of a useful supplement would be a detailed description of variables in your data.') }}

    {{ _('Metadata supplements are separate documents that appear to viewers of the dataset as downloadable resources. In many cases the dataset will also appear in search results based on the contents of its metadata supplements. Searching works for many common file formats (e.g. plain text, PDF, and many office document formats) but is not guaranteed to work for all files.') }}

    {{ _('Adding supplements to the metadata requires that you have editor privileges to the dataset.') }}

    {{ _('To add metadata supplements for a dataset, follow these steps:') }}

    1. {{ _('Open the dataset for editing and find the "Add new supplement" button on the left.') }}
    2. {{ _('In the following form, click the button to upload the supplementary document from your computer to Etsin.') }}
    3. {{ _('Enter a name and, optionally, a description for the supplement.') }}
    4. {{ _('Finally, be sure to confirm adding the supplement to your dataset by clicking "Add" at the bottom of the form.') }}

    {{ _('API') }}

    {{ _('Etsin supports standard')}} CKAN API {{ _('commands. In addition, Etsin supports addition and deletion of dataset editors with dataset_editor_add and dataset_editor_delete, respectively. ') }} {{ _('To add a dataset editor, provide also attributes: name (dataset\'s name), role (usually editor) and username (user login to add) ') }}

    {{ _('The metadata model of Etsin is more complex than the default model in CKAN. An example of a dataset that can be created in Etsin, using Curl: ') }}

    {# Manually written example mostly because pre doesn't work together with trans #}
    curl http://etsin.avointiede.fi/api/3/action/package_create --data-urlencode '{
        "agent": [
            {
                "URL": "http://url",
                "fundingid": "{{ _('Funding id') }}",
                "name": "{{ _('Funder') }}",
                "organisation": "{{ _('Project name') }}",
                "role": "funder"
            },
            {
                  "name": "{{ _('Owner') }}",
                  "role": "owner"
            },
            {
                  "name": "{{ _('Author') }}",
                  "organisation": "{{ _('Organization') }}",
                  "role": "author"
            }
        ],
        "algorithm": "{{ _('Algorithm') }}",
        "availability": "access_request",
        "checksum": "{{ _('Checksum') }}",
        "contact": [
            {
                  "URL": "http://url",
                  "email": "email@domain.com",
                  "name": "{{ _('Contact name') }}",
                  "phone": "{{ _('Phone') }}"
            }
        ],
        "direct_download_URL": "",
        "access_application_URL": "",
        "access_request_URL": "http://url",
        "discipline": "{{ _('Discipline') }}",
        "event": [
            {
                  "descr": "{{ _('Description') }}",
                  "type": "{{ _('Eg. collection') }}",
                  "when": "{{ _('Date in ISO 8601 format') }}",
                  "who": "{{ _('Eg. person') }}"
            }
        ],
        "geographic_coverage": "{{ _('Geographic coverage') }}",
        "langtitle": [
            {
                  "lang": "{{ _('Title language, eg. fin') }}",
                  "value": "{{ _('Title') }}"
            },
            {
                  "lang": "{{ _('Title language, eg. fin') }}",
                  "value": "{{ _('Title') }}"
            }
         ],
        "language": "{{ _('Dataset\'s language(s), eg. eng,fin') }}",
        "license_id": "{{ _('Eg. cc-by') }}",
        "mimetype": "{{ _('MIME type') }}",
        "name": "{{ _('Automatically generated, if left empty') }}",
        "pids": [
            {
                  "id": "PID",
                  "provider": "{{ _('Provider of the identifier') }}",
                  "type": "{{ _('Eg. data') }}",
                  "primary": "{{ _('True, if primary data identifier') }}"
            },
            {
                  "id": "PID",
                  "provider": "{{ _('Provider of the identifier') }}",
                  "type": "{{ _('Eg. version') }}"
            }
         ],
        "notes": "{{ _('Description') }}",
        "projdis": "True",
        "tag_string": "{{ _('Subjects as a comma separated string') }}",
        "temporal_coverage_begin": "{{ _('Time in ISO8601 format, eg. 2000-01-01T00:00:01') }}",
        "temporal_coverage_end": "{{ _('Time in ISO8601 format, eg. 2000-01-01T00:00:01') }}",
        "version": "{{ _('ISO8601 format, eg. 2014-06-06T07:07:07') }}",
        "owner_org": "{{ _('Organization, see organizations in Etsin web user interface.') }}",
        "private": "{{ _('True or false, private datasets are not added to the search index.') }}"
    }'
    -H "Authorization: {{ _('YOUR-API-KEY') }}"
                
    {% endblock %} {% block secondary_content %}

    {{ _('Table of contents') }}

    {% endblock %}