====== Content generation ======

===== Who is this guide for =====

  * Any user willing to add content to OD Mekong's CKAN module.
  * CKAN's administrators 

===== What this guide teaches =====

  * How to register as user on OD Mekong's CKAN instance
  * How to request permissions to admin
  * How admins can assign registered users to existing organizations
  * How to create datasets, set metadata and upload related resources.
  * How to share those created resources through Social Networks

===== Things to know beforehand =====

==== Datasets and resources ====

For CKAN purposes, data is published in units called “datasets”. A dataset is a parcel of data - for example, it could be the crime statistics for a region, the spending figures for a government department, or temperature readings from various weather stations. When users search for data, the search results they see will be individual datasets.

A dataset contains two things:

  * **Information or “metadata”** about the data. For example, the title and publisher, date, what formats it is available in, what license it is released under, etc.
  * **A number of “resources”**, which hold the data itself. CKAN does not mind what format the data is in. A resource can be a CSV or Excel spreadsheet, XML file, PDF document, image file, linked data in RDF format, etc. CKAN can store the resource internally, or store it simply as a link, the resource itself being elsewhere on the web. A dataset can contain any number of resources. For example, different resources might contain the data for different years, or they might contain the same data in different formats.

==== Different dataset types ====

On the Datahub 2 different types of datasets are currently stored/administered:
  * Dataset
  * Library records

==== Different User roles ====

CKAN users can register user accounts and log in. Login is not needed to search for and find data, but is needed for all publishing functions: datasets can be created, edited, etc by users with the appropriate permissions.

In the particular case of the OD Mekongs's CKAN instance, every user must belong to an existing organization in order to be able to upload datasets. After registering, users have to contact the administrator of the Organization they want to belong to in order to get the appropriate permissions assigned. Please refer to [[collaborating_organizations|Collaborating Organizations]] for the contact information of the different Administrators. The administrators will assign permissions within 12 hours.

Users can get following roles assigned within an Organization:

  * **Admin**: Administrators can give users Editor or Admin permissions within the Organization they coordinate and create/modify/review datasets.
  * **Editor**: Editors are only allowed to create Datasets which will be private until the admin reviews them.

==== Workflow within organisations and Review Process ====

All datasets uploaded to the CKAN must belong to an organisation. In order to avoid incorrect or non-valid information to be published and exposed on the platform following **Review Process** has been implemented:

  * Datasets will be uploaded usually by **Editors** of each organisation.

  * By default, Editors can only upload datasets marked as **Private**, which won't be visible by the users visiting the platform.

  * **Admins** of each organisation will get notified once a new dataset has been uploaded in order for them to review it. In case the information is valid, it will be made available. In the other case, the Admin will have to contact the editor and ask for a correction.

Each organisation will have at least one user with the Admin role (odmcambodia, odmcadmin, odmlaos, odmthailand, odmvietnam, odmmyanmar) and several editors. 

Note: a more sophisticated workflow for review, approval and dialogue on disputed datasets is currently being developed by ODI. This guide will be updated once it is finalised.

===== Registering a new user =====

To create a user ID, use the “Register” link at the top of any page. CKAN will ask for the following:

  * **Username** – choose a username using only letters, numbers, - and _ characters. For example, “jbloggs” or “joe_bloggs93”.
  * **Full name** – to be displayed on your user profile
  * **E-mail address** – this will not be visible to other users
  * **Password** – enter the same password in both boxes

{{ :user_registration.png?direct&600 }}

If there are problems with any of the fields, CKAN will tell you the problem and enable you to correct it. When the fields are filled in correctly, CKAN will create your user account and automatically log you in.

===== Managing your user profile =====

You can change the information that CKAN holds about you, including what other users see about you by editing your user profile. (Users are most likely to see your profile when you edit a dataset or upload data to an organization that they are following.) To do this, select the gearwheel symbol at the top of any page.

{{ setting_in_username.jpg?direct&600 }}

CKAN displays the user settings page. Here you can change:

  * Your username
  * Your full name
  * Your e-mail address (note: this is not displayed to other users)
  * Your profile text - an optional short paragraph about yourself
  * Your password

Make the changes you require and then select the “Update Profile” button.

===== Requesting an Organization's Admin to join =====

Once registered, the new user needs to be assigned to an Organization before being able to add datasets to the platform. For that, the user needs to [[collaborating_organizations|contact an Administrator]] and request Editor/Admin permissions within the organization via email.

Note: A new communications system within CKAN is currently being developed by ODI. This guidewill be updated once that is finalised, but currently external communications such as email or Skype are recommended to complete this process.

===== For Admins: Assigning a user to an existing Organization =====

In order for Users to be able to upload datasets, they need first to be assigned to a organization by an Admin. This can be done as follows:

After logging with administrator credentials for the corresponding Organization. Admin user can head to the page of the organization (in this example OD Cambodia).

{{ :ckan_admin_manage_org.png?600 }}


By clicking the **Manage** button and then the members tab, a screen appears where users belonging to the organization and their roles are listed. By clicking the **Add Member** button, the Admin can specify a username and assign it a role (most of the times the **Editor** role will be selected).

{{ :ckan_add_user_org.png?600 |}}

Users should be notified about their new Role so they can begin uploading content.

===== Uploading datasets to CKAN =====

Note: You need to be a member of an organization in order to add and edit datsets. See the section Creating an organization below. Also, before adding a dataset or library item to CKAN, please **search** its title to see if it already exists in the system. If so, please compare your document to the version previously archived. If you have an update or newer edition, please add it to the existing record rather than creating a new one. See **Step 3: Add resources** below.
==== Step1: Go to create Dataset screen ====
You can access CKAN’s “Create dataset” screen in two ways:
  - Hover the “DataHub” link at the top of any page and then select "Search DataHub". From this, above the search box, select the “Add Dataset” button.
  - Alternatively, hover the “DataHub” link at the top of any page and then select "Organisation". Now select the organisation that should own your new dataset. Provided that you are a member of this organisation, you can now select the “Add Dataset” button above the search box.
==== Step2: Specify dataset's basic info ==== 

There are 6 tabs for the categories of MetaData: 
     Description
     Temporal
     Spatial
     DataQuality
     Contact
     Management 
The tabs appear on the left hand side of the form.

===Under "Description" tab===

  * **Title** – this title will be unique across CKAN, so make it brief but specific. E.g. “UK population density by region” is better than “Population figures”.
  * <WRAP center round important 90%> This field can only contain alphanumeric characters or symbols: -_. This means that no Thai, Vietnamese, Lao, Chinese or Burmese characters are allowed. Please use English.
</WRAP>
  * ** URL ** - normally, this field gets generated automatically based on the specified title.

{{ ::create_dataset.png?direct&600 }}

  * **Abstract** – You can add a short description of the dataset here, including information such as where the data is from and any information that people will need to know when using the data.
  * **Language** - Language(s) of the dataset, including resources within the dataset
  * **Organisation name** - If you are a member of any organisation, this drop-down will enable you to choose which one should own the dataset. Ensure the default chosen is the correct one before you proceed. (Probably most users will be in only one organisation. If this is you, CKAN will have chosen your organisation by default and you need not do anything.)
  * **Visibility** – a Public dataset is public and can be seen by any user of the site. A Private dataset can only be seen by members of the organization owning the dataset and will not show up in searches by other users.

===Under "Management" tab===

{{ ::create_dataset-management.png?direct&600 }}

  * **License** – it is important to include license information so that people know how they can use the data. This field should be a drop-down box. If you need to use a license not on the list, contact your site administrator.
  
  * **Version** - Enter the version of your dataset, starting with 1.0.



  * **Database Table** - This check box is located towards the bottom of the Management form. It is used to distinguish whether a resource table contains relevant relational data that is used to call upon for data visualisations, dashboards or profiles. Please select yes if this is TRUE or leave it blank otherwise. 

{{ ::partners:database_table.jpg?300 }}

  * **Keywords** – here you may add keywords or tags that will help people find the data and link it with other related data. Examples could be “population”, “crime”, “East Anglia”. Hit the <return> key between tags. If you enter a tag wrongly, you can use its delete button to remove it before saving the dataset.
<WRAP center round important 90%>
This field can only contain alphanumeric characters or symbols: -_. This means that no Thai, Vietnamese, Lao, Chinese or Burmese characters are allowed. Please use English.
</WRAP>

==== Complete ODI Metadata template ==== 

The remainder of the forms contain fields in ODI's Metadata template. These are designed to allow as descriptive metadata as possible to maximise the usability of the data and clearly describe any limitations. Not all fields will be applicable to all datasets, but fields marked with a "*" are mandatory. Please see a detailed description of all fields and their usage at the [[metadata|ODI Metadata template page.]]

When you have filled in the information on this page, select the “Next: Add Data” button. (Alternatively select “Cancel” to discard the information filled in.)

==== Step 3: Add resources ====



This is where you will add one or more “resources” which contain the data for this dataset. Choose a file or link for your data resource and select the appropriate choice at the top of the screen:

  * If you are giving CKAN a link to the data, like http://example.com/mydata.csv, then select “Link to a file” or “Link to an API”. (If you don’t know what an API is, you don’t need to worry about this option - select “Link to a file”.)
  * If the data to be added to CKAN is in a file on your computer, select “Upload a file”. CKAN will give you a file browser to select it.

Add the other information on the page. CKAN does not require this information, but it is good practice to add it:

  * **Name** – a name for this resource, e.g. “Population density 2011, CSV”. Different resources in the dataset should have different names.
  * **Description** – a short description of the resource.
  * **Format** – the file format of the resource, e.g. CSV (comma-separated values), XLS, JSON, PDF, etc.

If you have more resources (files or links) to add to the dataset, select the “Save & add another” button. When you have finished adding resources, select “Finish”.

{{ :additional_data_set.png?600 }}


==== Step 5: Finish ====

Select the ‘Finish’ button. CKAN creates the dataset and shows you the result. You have finished!

You should be able to find your dataset by typing the title, or some relevant words from the description, into the search box on any page in your CKAN instance. 

==== Step 6: Inform the administrator for review and publication ====

User with Editor role can only create datasets marked as **private**, in order for them to be published, users need to contact the Organization's administrator and request their publication. In future this will be automated, but please contact the administrator until that module is complete.

==== Step 7: Adding the dataset to a specific group ====

Datasets are categorized in different groups depending on the nature of the information. On http://data.opendevelopmentmekong.net/group, the current list of groups can be seen.

In order to add our newly created dataset into a group, let's say Maps, we have to click on the title of our dataset so the detail page gets opened and there, we have to select the groups tab which shows us in which groups the datasets is already added and gives us the possibility to assign this dataset to another group.

{{ :screenshot_from_2015-04-03_14_34_37.png?600 }}

===== Sharing dataset information on Social Networks =====

URLs to Datasets can be shared from within the datasets' page. On the bottom left corner of the page you can see links for sharing the dataset's URL on different social networks:

{{ :social_media.jpg?direct&600 }}