====== Adding maps to CKAN ======

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

  * ODM's Mappers working with Geoserver
  * Staff maintaining the spatial information rsources

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

  * How to create a new map layer on Geoserver
  * How to download the different data representations of a map layer
  * How to create a dataset map on CKAN and add the downloaded representations as its resources both linking and/or uploading them.

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

==== Resources on CKAN can be linked or downloaded ====

Depending on the format and size of the downloaded files from geosever, editors will have to do the decision between linking the file (providing url) or uploading it into CKAN. As a rule of thumb, file formats that will be visualized automatically by ckan ( geojson, png, pdf) should be uploaded. Big-sized would preferably be linked.

==== Geoserver access requires login credentials ====

In order to complete some of the tasks indicated in this guide, users would need to have the corresponding access credentials to the geoserver instance. If you do not know or have them, [[collaborating_organizations|contact an administrator]]

===== Creating a new map layer on geoserver =====

<WRAP center round todo 90%>
TODO: Please, complete this section specifying instructions on how to create a new map layer on Geoserver
</WRAP>

===== Downloading representations of the layers on geoserver or obtaining their link =====
 
Let's take as example the Layer titled **Provinces** on http://geoserver.opendevelopmentmekong.net/geoserver/index.html.

After clicking on the **Layer preview** menu on the sidebar and searching for the term //Provinces//, a similar screen as this one will be presented.

{{ :bildschirmfoto_2015-04-03_um_11.51.05.png?600 |}}

On the right side of the table we find a dropbox box that offers the possibility to export the layers in very different formats. The formats that we would be most interested in would be:

  * **OpenLayers** : An embeddable html window showing a map, on-click data details and zoom controls. This resource cannot be uploeaded so it needs to be linked.
  * **Geojson**: JSON formatted file with spatial information. Will be visualized nativelly by CKAN and it is convenient to be uploaded as resource in order to reduce load times.
  * **PNG**: Image representation of the map.Will be visualized nativelly by CKAN and it is convenient to be uploaded as resource in order to reduce load times.
  * **PDF**: PDF document with an image of the map on a page.Will be visualized nativelly by CKAN and it is convenient to be uploaded as resource in order to reduce load times.
  * **KML**: XML representaiton used mostly by Google Earth. Geoserver offers 3 possibilities ( network links, simple and compressed)

<WRAP center round help 90%>
To discuss: Which one would be more convenient.
</WRAP>

  * **CSV**: Comma separated values representation. Will be visualized nativelly by CKAN and it is convenient to be uploaded as resource in order to reduce load times.

(Insert image for dropdown box here)

In order to download one of them, the corresponding format just needs to be selected from the dropdown box.

Obtaining the link to them implies composing the correct URL to call, which is specific for each type of format and can be composed by replacing the placeholders <GEOSERVER_URL>, <NAMESPACE>, <LAYER_NAME>, <WIDTH>, <HEIGHT> and <FORMAT> form the following URLs:

==== WMS Service ====

<code><GEOSERVER><NAMESPACE>/wms?service=WMS&version=1.1.0&request=GetMap&layers=<NAMESPACE>:<LAYER_NAME>&styles=&bbox=211430.86563420878,1144585.4696614784,784623.3606298851,1625594.694892376&width=<WIDTH>&height=<HEIGHT>&srs=EPSG:32648&format=<FORMAT></code>

Where <FORMAT> can be one of following values:

  * **Open Layers**: application/openlayers Example: http://geoserver.opendevelopmentmekong.net/geoserver/Topography/wms?service=WMS&version=1.1.0&request=GetMap&layers=Topography:Provinces&styles=&bbox=211430.86563420878,1144585.4696614784,784623.3606298851,1625594.694892376&width=512&height=429&srs=EPSG:32648&format=application/openlayers
  * **PNG**: image/png Example: http://geoserver.opendevelopmentmekong.net/geoserver/Topography/wms?service=WMS&version=1.1.0&request=GetMap&layers=Topography:Provinces&styles=&bbox=211430.86563420878,1144585.4696614784,784623.3606298851,1625594.694892376&width=512&height=429&srs=EPSG:32648&format=image%2Fpng
  * **PDF**: application/pdf Example: http://geoserver.opendevelopmentmekong.net/geoserver/Topography/wms?service=WMS&version=1.1.0&request=GetMap&layers=Topography:Provinces&styles=&bbox=211430.86563420878,1144585.4696614784,784623.3606298851,1625594.694892376&width=512&height=429&srs=EPSG:32648&format=application/pdf

==== WFS Service ====

<code><GEOSERVER><NAMESPACE>/ows?service=WFS&version=1.0.0&request=GetFeature&typeName=<NAMESPACE>:<LAYER>&srsName=EPSG:4326&outputFormat=<FORMAT></code>

  * **Geojson**: json Example: http://geoserver.opendevelopmentmekong.net/geoserver/Topography/ows?service=WFS&version=1.0.0&request=GetFeature&typeName=Topography:Provinces&srsName=EPSG:4326&outputFormat=json
  * **CSV**: csv Example: http://geoserver.opendevelopmentmekong.net/geoserver/Topography/ows?service=WFS&version=1.0.0&request=GetFeature&typeName=Topography:Provinces&srsName=EPSG:4326&outputFormat=csv

===== Creating a new map dataset and upload or link the downloaded resources =====

Now that we have downloaded the resources or have noted down the links, [[http://wiki.opendevelopmentmekong.net/content_generation#step1go_to_create_dataset_screen|we can create a new dataset]], [[http://wiki.opendevelopmentmekong.net/content_generation#step_3add_resources|add its resources]] and [[http://wiki.opendevelopmentmekong.net/content_generation#step_7adding_the_dataset_to_a_specific_group|assign it to the Maps group]].