<!--
  Licensed to the Apache Software Foundation (ASF) under one
  or more contributor license agreements.  See the NOTICE file
  distributed with this work for additional information
  regarding copyright ownership.  The ASF licenses this file
  to you under the Apache License, Version 2.0 (the
  "License"); you may not use this file except in compliance
  with the License.  You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

  Unless required by applicable law or agreed to in writing,
  software distributed under the License is distributed on an
  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
  KIND, either express or implied.  See the License for the
  specific language governing permissions and limitations
  under the License.
-->
<chapter id="tasks">
	<title>Tasks</title>
	
	<section id="tasks_manage_connections">
		<title>Managing connections</title>
		<section id="tasks_manage_connections_create">
			<title>Creating a connection</title>
			<simplesect>
				<title>Using the New Connection wizard</title>
				<para>
					To create a new connection please use the 
					<link linkend="tools_newconnection_wizard">New Connection wizard</link>.
				</para>
			</simplesect>
			<simplesect>
				<title>Duplicating an existing connection</title>
				<para>
					It is also possible to duplicate an existing connection. This is helpful
					if the new connection has similar connection parameters:
					<orderedlist numeration="arabic">
						<listitem>
							<para>
								Select the connection you want to duplicate and select 
								<inlinemediaobject><imageobject><imagedata scale="50" fileref="icons/copy.gif" format="GIF"/></imageobject></inlinemediaobject>
								<emphasis role="strong">Copy Connection</emphasis> from context menu
								or use the  
								<shortcut><keycombo><keycap>Strg</keycap><keycap>C</keycap></keycombo></shortcut>
								shortcut.
							</para>
						</listitem>
						<listitem>
							<para>
								Afterward select
								<inlinemediaobject><imageobject><imagedata scale="50" fileref="icons/paste.gif" format="GIF"/></imageobject></inlinemediaobject>
								<emphasis role="strong">Paste Connection</emphasis> from context menu
								or use the  
								<shortcut><keycombo><keycap>Strg</keycap><keycap>V</keycap></keycombo></shortcut>
								shortcut. Observe the new connection, prefixed with "Copy of ".
							</para>
						</listitem>
						<listitem>
							<para>
								<link linkend="tasks_manage_connections_rename">Rename</link> the connection to your needs.
							</para>
						</listitem>
						<listitem>
							<para>
								<link linkend="tasks_manage_connections_modify">Modify</link> the connection parameters to your needs.
							</para>
						</listitem>
					</orderedlist>
				</para>
			</simplesect>
		</section>
		<section id="tasks_manage_connections_modify">
			<title>Modifying connection parameters</title>
			<para>
				The connection parameters could be modified in the 
				<link linkend="tools_connection_properties">Connection properties</link>.
				Select a connection and choose 
				<emphasis role="strong">Properties...</emphasis>
				from context menu or press 
				<shortcut><keycombo><keycap>Alt</keycap><keycap>Enter</keycap></keycombo></shortcut>
				to open the properties dialog.
			</para>
			<para>
				Note: A connection must be closed in order to modify its connection parameters.
			</para>
		</section>
		<section id="tasks_manage_connections_rename">
			<title>Renaming a connection</title>
			<para>
				To rename a connection select a connection and choose 
				<emphasis role="strong">Rename Connection...</emphasis>
				from context menu or press 
				<shortcut><keycap>F2</keycap></shortcut>.
			</para>
			<para>
				In the opened dialog enter the new name and press 
				<shortcut><keycap>OK</keycap></shortcut>.
			</para>
		</section>
		<section id="tasks_manage_connections_delete">
			<title>Deleting a connection</title>
			<para>
				To delete a connection select a connection and choose 
				<inlinemediaobject>
					<imageobject>
						<imagedata scale="50"
							fileref="icons/delete.gif" format="GIF" />
					</imageobject>
				</inlinemediaobject>
				<emphasis role="strong">Delete Connection</emphasis>
				from context menu or press <emphasis role="strong">Delete</emphasis>.
			</para>
			<para>
				Note: A connection must be closed in order to delete it.
			</para>
		</section>
		<section id="tasks_manage_connections_open">
			<title>Opening a connection</title>
			<para>
				A connection is automatically opened when expanding the DIT or 
				when performing a search.
			</para>
			<para>
				To open a connection explicitely choose one of the following options:
				<itemizedlist>
					<listitem>
						<para>
							In the Connections view select a connection and choose
							<inlinemediaobject>
								<imageobject>
									<imagedata scale="50"
										fileref="icons/connection_connect.gif" format="GIF" />
								</imageobject>
							</inlinemediaobject>
							<emphasis role="strong">Open Connection</emphasis>
							from context menu or from toolbar.
						</para>
					</listitem>
					<listitem>	
						<para>
							Double-click a connection.
						</para>
					</listitem>
				</itemizedlist>				
			</para>
		</section>
		<section id="tasks_manage_connections_close">
			<title>Closing a connection</title>
			<para>
				To close a connection select a connection and choose
				<inlinemediaobject>
					<imageobject>
						<imagedata scale="50"
							fileref="icons/connection_disconnect.gif" format="GIF" />
					</imageobject>
				</inlinemediaobject>
				<emphasis role="strong">Close Connection</emphasis>
				from context menu or from toolbar.
			</para>
		</section>
		<section id="tasks_manage_connections_secure">
			<title>Enabling secure connections</title>
			<para>
				Apache Directory Studio supports secure connections using SSL (ldaps) or StartTLS extended operation. 
				Select a proper encryption method in the 
				<link linkend="tools_connection_properties">Connection properties</link>.
			</para>
		</section>
		<section id="tasks_manage_connections_share">
			<title>Sharing connections</title>
			<para>
				There are two ways to export and import connections.
				This may be useful if you want to copy your connections from one computer 
				to another or if you want to share connection parameters with other users.
				You could also use this features to backup your defined connections.
			</para>
			<simplesect>
				<title>Import/Export connections</title>
				<para>
					You could use the  
					<link linkend="tools_exportconnection_wizard">Export Connection wizard</link>
					and 
					<link linkend="tools_importconnection_wizard">Import Connection wizard</link>
					to export and import connections.
				</para>
			</simplesect>
			<simplesect>
				<title>Copy/Paste connections as LDAP URL</title>
				<para>
					A more simple way is to copy/paste connections as LDAP URL.
				</para>
				<para>
					RFC 2255 specifies the LDAP URL format. Apache Directory Studio uses the 
					host and port field	and uses X- extensions for all other connection paramter.
				</para>
				<para>
				<informaltable frame="all">
					<tgroup cols="4">
						<colspec colname="Parameter" colwidth="1*" />
						<colspec colname="Description" colwidth="1*" />
						<colspec colname="Possible values" colwidth="1*" />
						<colspec colname="Default" colwidth="1*" />
						<thead>
							<row>
								<entry>Parameter</entry>
								<entry>Description</entry>
								<entry>Possible values</entry>
								<entry>Default</entry>
							</row>
						</thead>
						<tbody>
							<row>
								<entry>X-CONNECTION-NAME</entry>
								<entry>The connection name.</entry>
								<entry>Any name, must be URL encoded</entry>
								<entry>Current date</entry>
							</row>
							<row>
								<entry>X-ENCRYPTION</entry>
								<entry>The encryption to use.</entry>
								<entry>none, ldaps, StartTLS</entry>
								<entry>none</entry>
							</row>
							<row>
								<entry>X-AUTH-METHOD</entry>
								<entry>The authentication to use.</entry>
								<entry>Anonymous, Simple, DIGEST-MD5, CRAM-MD5</entry>
								<entry>Simple imf X-BIND-USER is present, else Anonymous</entry>
							</row>
							<row>
								<entry>X-BIND-USER</entry>
								<entry>The bind DN or user.</entry>
								<entry>Any DN, must be URL encoded</entry>
								<entry>none</entry>
							</row>
							<row>
								<entry>X-BIND-PASSWORD</entry>
								<entry>The bind password.</entry>
								<entry></entry>
								<entry>none</entry>
							</row>
							<row>
								<entry>X-SASL-REALM</entry>
								<entry>The SASL realm.</entry>
								<entry></entry>
								<entry>none</entry>
							</row>
							<row>
								<entry>X-BASE-DN</entry>
								<entry>The base DN.</entry>
								<entry>A valid base DN, none to get base DNs from the Root DSE</entry>
								<entry>none</entry>
							</row>
							<row>
								<entry>X-COUNT-LIMIT</entry>
								<entry>The count limit.</entry>
								<entry>A positive integer, 0 for no count limit</entry>
								<entry>0</entry>
							</row>
							<row>
								<entry>X-TIME-LIMIT</entry>
								<entry>The time limit in seconds.</entry>
								<entry>A positive integer, 0 for no time limit</entry>
								<entry>0</entry>
							</row>
							<row>
								<entry>X-ALIAS-HANDLING</entry>
								<entry>The alias handling method.</entry>
								<entry>NEVER, SEARCHING, FINDING, ALWAYS</entry>
								<entry>ALWAYS</entry>
							</row>
							<row>
								<entry>X-REFERRAL-HANDLING</entry>
								<entry>The referral handling method.</entry>
								<entry>FOLLOW, IGNORE, MANAGE</entry>
								<entry>FOLLOW</entry>
							</row>
							<row>
								<entry>X-FETCH-SUBENTRIES</entry>
								<entry>If present the subentries control is activated.</entry>
								<entry>no value</entry>
								<entry>-</entry>
							</row>
							<row>
								<entry>X-PAGED-SEARCH</entry>
								<entry>If present the paged control is activated.</entry>
								<entry>no value</entry>
								<entry>-</entry>
							</row>
							<row>
								<entry>X-PAGED-SEARCH-SIZE</entry>
								<entry>The paged search size.</entry>
								<entry>Any positive integer</entry>
								<entry>100</entry>
							</row>
							<row>
								<entry>X-PAGED-SEARCH-SCROLL-MODE</entry>
								<entry>If present the scroll mode is activated.</entry>
								<entry>No value</entry>
								<entry>-</entry>
							</row>
						</tbody>
					</tgroup>
				</informaltable>
				</para>
				<para>
					Here's an example how such an URL looks like:
					ldap://localhost:10389/????X-CONNECTION-NAME=ApacheDS,X-BIND-USER=uid=admin%2cou=system,X-BIND-PASSWORD=secret,X-COUNT-LIMIT=1000
				</para>
				<para>
					When you copy a connection within the Connections view it is copied
					in the described format to your clipboard. You could then paste this LDAP URL
					into a text editor or to an email.
				</para>
				<para>
					The same way you could copy an LDAP URL from somewhere and paste it into the 
					Connections view.
				</para>
			</simplesect>
		</section>
	</section>	

	
	<section id="tasks_browse_directory">
		<title>Browsing directory</title>
		
		<section id="tasks_browse_directory_handle_large_trees">
			<title>Handling large number of entries</title>
			<para>
				A directory may have entries with thousands of child entries. 
				It is not recommended to fetch all these children when
				browsing because this increases directory and network load 
				and is very time consuming.
			</para>
			<simplesect id="tasks_browse_directory_handle_large_trees_limit">
				<title>Limiting number of fetched entries</title>
				<para>
					It is recommended to limit the number of returned 
					entries. The limit is defined in  
					<link linkend="tools_connection_properties_browser_options">Connection properties</link>.
				</para>
			</simplesect>
			
			<simplesect id="tasks_browse_directory_filter">
				<title>Filtering children</title>
				<para>
					Another option is to use a filter to limit the fetched children.
					Choose
					<inlinemediaobject>
						<imageobject>
							<imagedata scale="50"
								fileref="icons/filter_dit.gif" format="GIF" />
						</imageobject>
					</inlinemediaobject>
					<emphasis role="strong">Filter Children...</emphasis>
					from context menu. In the opened dialog you could
					define a LDAP filter. Hit 
					<shortcut><keycombo><keycap>Strg</keycap><keycap>Space</keycap></keycombo></shortcut> 
					to get content assistance. The drop-down list
					provides a history of recently used
					filters. A click to the
					<emphasis role="strong">
						Filter Editor
					</emphasis>
					button opens the 
					<link linkend="tools_filter_editor_dialog">Filter Editor dialog</link>.
				</para>
			</simplesect>
			
		</section>
		
		<section id="tasks_browse_directory_show_metadata">
			<title>Showing RootDSE and Schema entry</title>
			<para>
				To make RootDSE and Schema entry visible in the Browser view 
				enable <emphasis role="strong">Show Directory Metadata</emphasis>
				in the Browser's drop down menu. 
			</para>
		</section>
		
		<section id="tasks_browse_directory_show_subentries">
			<title>Showing subentries</title>
			<para>
				Subentries are a special kind of entries used for managing the 
				administration of different aspects of the directory. By default 
				they are not visible. To make them visible in the Browser view 
				enable <emphasis role="strong">Fetch subentries</emphasis> in the 
				<link linkend="tools_connection_properties_browser_options">Connection properties</link>. 
				
			</para>
		</section>
		
		<section id="tasks_browse_directory_display_attributes">
			<title>Displaying entry's attribute</title>
			<para>
				Select an entry in the Browser view. The Entry editor will be
				opened and shows the entry's attributes.
			</para>
		</section>
		
		<section id="tasks_browse_directory_filter_attributes">
			<title>Filtering entry's attribute</title>
			<para>
				Please see
				<link linkend="tools_entry_editor_quickfilter">
					Quick Filter
				</link>
				in Entry editor features.
			</para>
		</section>
		
	</section>
		  
	<section id="tasks_manage_entries">
		<title>Managing entries</title>	
		
		<section id="tasks_manage_entries_create">
			<title>Creating an entry</title>
			<para>
				To create a new entry please use the 
				<link linkend="tools_newentry_wizard">New Entry wizard</link>.
			</para>
		</section>
		
		<section id="tasks_manage_entries_rename">
			<title>Renaming an entry</title>
			<para>
				To rename an entry please use the 
				<link linkend="tools_rename_entry_dialog">Rename Entry dialog</link>.
			</para>
		</section>
		
		<section id="tasks_manage_entries_move">
			<title>Moving entries</title>
			<para>
				To move entries to another parent please use the 
				<link linkend="tools_move_entries_dialog">Move Entry dialog</link>.
			</para>
		</section>
		
		<section id="tasks_manage_entries_delete">
			<title>Deleting entries</title>
			<para>
				To delete entries select the entries you would like to delete and
				choose 
				<inlinemediaobject>
					<imageobject>
						<imagedata scale="50"
							fileref="icons/delete.gif" format="GIF" />
					</imageobject>
				</inlinemediaobject>
				<emphasis role="strong">Delete</emphasis>
				from context menu
				or press <shortcut><keycap>Delete</keycap></shortcut> key.
			</para>
		</section>
		
		<section id="tasks_manage_entries_addattribute">
			<title>Adding an attribute</title>
			<para>
				<orderedlist numeration="arabic">
					<listitem>
						<para>
							Use the 
							<link linkend="tools_attribute_wizard">Attribute wizard</link>
							to specify the attribute.
						</para>
					</listitem>
					<listitem>
						<para>
							After finishing the wizard a proper 
							<link linkend="tools_value_editors">Value editor</link>
							is invoked. Enter the value and press 
							<shortcut><keycap>Enter</keycap></shortcut>.
						</para>
					</listitem>
				</orderedlist>
			</para>
		</section>
		
		<section id="tasks_manage_entries_addvalue">
			<title>Adding a value</title>
			<para>
				<orderedlist numeration="arabic">
					<listitem>
						<para>
							Select the attribute where you would like to add a value.
						</para>
					</listitem>
					<listitem>
						<para>
							Choose 
							<inlinemediaobject>
								<imageobject>
									<imagedata scale="50" fileref="icons/value_add.gif"
										format="GIF" />
								</imageobject>
							</inlinemediaobject>
							<emphasis role="strong">New Value</emphasis>
							from tool bar or context menu or hit 
							<shortcut><keycombo>
								<keycap>Strg</keycap>
								<keycap>+</keycap>
							</keycombo></shortcut>.
							This invokes a proper 
							<link linkend="tools_value_editors">Value editor</link>
						</para>
					</listitem>
					<listitem>
						<para>
							Enter the value and press 
							<shortcut><keycap>Enter</keycap></shortcut>.
						</para>
					</listitem>
				</orderedlist>
			</para>
		</section>
		
		<section id="tasks_manage_entries_modifyvalue">
			<title>Modifying a value</title>
			<para>
				<orderedlist numeration="arabic">
					<listitem>
						<para>
							Select the value you would like to edit.
						</para>
					</listitem>
					<listitem>
						<para>
							Invoke the default 
							<link linkend="tools_value_editors">Value editor</link>
							by pressing 
							<shortcut><keycap>Enter</keycap></shortcut> or
							<shortcut><keycap>F7</keycap></shortcut> or
							double-click the value.
						</para>
						<para>
							or
						</para>
						<para>
							Invoke a custom 
							<link linkend="tools_value_editors">Value editor</link>
							by choosing one from 
							<emphasis role="strong">Edit Value With</emphasis>
							in the context menu.
						</para>
					</listitem>
					<listitem>
						<para>
							Modify the value and press 
							<shortcut><keycap>Enter</keycap></shortcut>.
						</para>
					</listitem>
				</orderedlist>
			</para>
		</section>
		
		<section id="tasks_manage_entries_deletevalue">
			<title>Deleting attributes and values</title>
			<para>
				To delete attributes and values select the 
				attributes and values you would like to delete and choose 
				<inlinemediaobject>
					<imageobject>
						<imagedata scale="50"
							fileref="icons/delete.gif" format="GIF" />
					</imageobject>
				</inlinemediaobject>
				<emphasis role="strong">Delete</emphasis>
				from tool bar or context menu
				or press <shortcut><keycap>Delete</keycap></shortcut> key.
			</para>
		</section>		
		
		<section id="tasks_manage_entries_modifyobjectclass">
			<title>Modifying the object class</title>
			<para>
				To modify the object class please use the 
				<link linkend="tools_editentry_wizard">Edit Entry wizard</link>.
			</para>
		</section>		
	</section>

</chapter>
