summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorJeroen van Meeuwen (Kolab Systems) <vanmeeuwen@kolabsys.com>2012-05-11 12:55:53 (GMT)
committerJeroen van Meeuwen (Kolab Systems) <vanmeeuwen@kolabsys.com>2012-05-11 12:55:53 (GMT)
commit554064b4a903f3009964426a7e74a0c199d1f4fc (patch)
tree41c82cedc1c202135ad9d2d6b7a137886a08a84b
parent39c9e777ab1aa18046848e6564a48032a6ba137e (diff)
downloadkolab-docs-554064b4a903f3009964426a7e74a0c199d1f4fc.tar.gz
Add documentation on editing the user_types in the Kolab Web Administration Panel manually
-rw-r--r--Administrator_Guide/en-US/Kolab_Web_Administration_Panel.xml401
-rwxr-xr-xAdministrator_Guide/en-US/part-Kolab_Server.xml1
-rw-r--r--Installation_Guide/en-US/Kolab_Server_First_Login.xml21
3 files changed, 422 insertions, 1 deletions
diff --git a/Administrator_Guide/en-US/Kolab_Web_Administration_Panel.xml b/Administrator_Guide/en-US/Kolab_Web_Administration_Panel.xml
new file mode 100644
index 0000000..9447428
--- /dev/null
+++ b/Administrator_Guide/en-US/Kolab_Web_Administration_Panel.xml
@@ -0,0 +1,401 @@
+<?xml version='1.0' encoding='utf-8' ?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+<!ENTITY % BOOK_ENTITIES SYSTEM "Administrator_Guide.ent">
+%BOOK_ENTITIES;
+]>
+<chapter id="chap-Administrator_Guide-Kolab_Web_Administration_Panel">
+ <title>Kolab Web Administration Panel</title>
+ <section id="sect-Administrator_Guide-Kolab_Web_Administration_Panel-Editing_user_types">
+ <title>Editing <literal>user_types</literal></title>
+ <para>
+ The <literal>user_types</literal> table in the MySQL <literal>kolab</literal> database contains the following columns:
+ </para>
+ <para>
+ <itemizedlist>
+ <listitem>
+ <formalpara id="form-Administrator_Guide-Editing_user_types-id">
+ <title>id</title>
+ <para>
+ A unique ID.
+ </para>
+
+ </formalpara>
+
+ </listitem>
+ <listitem>
+ <formalpara id="form-Administrator_Guide-Editing_user_types-key">
+ <title>key</title>
+ <para>
+ A machine-readable key identifying the user type.
+ </para>
+
+ </formalpara>
+
+ </listitem>
+ <listitem>
+ <formalpara id="form-Administrator_Guide-Editing_user_types-name">
+ <title>name</title>
+ <para>
+ A human-readable name.
+ </para>
+
+ </formalpara>
+
+ </listitem>
+ <listitem>
+ <formalpara id="form-Administrator_Guide-Editing_user_types-description">
+ <title>description</title>
+ <para>
+ A description of the user type.
+ </para>
+
+ </formalpara>
+
+ </listitem>
+ <listitem>
+ <formalpara id="form-Administrator_Guide-Editing_user_types-attributes">
+ <title>attributes</title>
+ <para>
+ The actual settings. Please see <xref linkend="sect-Administrator_Guide-Editing_user_types-Attributes_Reference" /> for a full reference, and <xref linkend="proc-Administrator_Guide-Editing_user_types-Manually_Changing_the_user_types_Available" /> for the procedure to edit these settings manually.
+ </para>
+
+ </formalpara>
+
+ </listitem>
+
+ </itemizedlist>
+
+ </para>
+ <procedure id="proc-Administrator_Guide-Editing_user_types-Manually_Changing_the_user_types_Available">
+ <title>Manually Changing the <literal>user_types</literal> Available</title>
+ <step>
+ <para>
+ Sample scripts are provided as part of the <application>kolab-webadmin</application> package. Use the following command to locate these scripts, called <emphasis>sample-insert-user_types.php</emphasis>;
+ </para>
+ <para>
+
+<screen># <userinput>rpm -qld kolab-webadmin</userinput></screen>
+
+ </para>
+
+ </step>
+ <step>
+ <para>
+ Copy the relevant example file to one directory above the <filename>public_html/</filename> directory, like so:
+ </para>
+ <para>
+
+<screen># <userinput>cp -a /path/to/sample-insert-user_types.php \</userinput>
+ <userinput>/usr/share/kolab-webadmin/insert-user_types.php</userinput></screen>
+ </para>
+ </step>
+ <step>
+ <para>
+ Edit the file to reflect your needs. For example, to avoid the <literal>mail</literal> attribute from being automatically generated, remove <literal>$attributes['auto_form_fields']['mail']</literal>.
+ </para>
+ </step>
+ <step>
+ <para>
+ You may want to insert <literal>$attributes["form_fields"]["mail"]</literal> to insert back a form field that allows supplying a mail attribute value for the user type.
+ </para>
+ </step>
+ <step>
+ <para>
+ Once done editing, check the syntax;
+ </para>
+ <para>
+
+<screen># <userinput>php -l insert-user_types.php</userinput></screen>
+
+ </para>
+ </step>
+ <step>
+ <para>
+ Execute the file to replace the user types currently in the database;
+ </para>
+ <para>
+
+<screen># <userinput>php insert-user_types.php</userinput></screen>
+
+ </para>
+ </step>
+ <step>
+ <para>
+ Log out and log back in to the web admin.
+ </para>
+ </step>
+
+ </procedure>
+
+ <section id="sect-Administrator_Guide-Editing_user_types-Attributes_Reference">
+ <title>Attributes Reference</title>
+ <para>
+ The attributes column for user types describes which form fields are to be offered to the <emphasis>add user</emphasis> dialog for each type of user available.
+ </para>
+ <para>
+ It is an object consisting of three types of form fields, namely;
+ </para>
+ <para>
+ <orderedlist>
+ <listitem>
+ <para>
+ <literal>auto_form_fields</literal>, or form fields for which the value is generated automatically (from values that are entered in other form fields).
+ </para>
+ <para>
+ Example form fields for which the value can be generated automatically include <literal>displayname</literal> and <literal>cn</literal>.
+ </para>
+
+ </listitem>
+ <listitem>
+ <para>
+ <literal>form_fields</literal>, for form fields to which the user or administrator is to provide input.
+ </para>
+ <para>
+ Example form fields that users or administrators would provide input to include <literal>givenname</literal> and <literal>surname</literal>.
+ </para>
+
+ </listitem>
+ <listitem>
+ <para>
+ <literal>fields</literal>, for form fields that are hidden from plain sight, and cannot be edited by the user or administrator.
+ </para>
+ <para>
+ Example fields that would be configured as immutable, or static, and therefore be hidden from the client interface include <literal>objectclass</literal>.
+ </para>
+
+ </listitem>
+
+ </orderedlist>
+
+ </para>
+ <para>
+ The structure of the <literal>attributes</literal> attribute value is:
+ </para>
+ <para>
+
+<screen language="PHP/PHP">Array(
+ "&lt;form_field_type&gt;" =&gt; Array(
+ "&lt;form_field_name&gt;" =&gt; Array(
+ ['data' =&gt; Array(
+ "&lt;form_field_name&gt;"[,
+ "&lt;form_field_name&gt;"[,
+ "&lt;form_field_name&gt;"],]
+ ),]
+ ['type' =&gt; "text|select|multiselect|...",]
+ ['values' =&gt; Array(
+ "&lt;value1&gt;"[,
+ "&lt;value1&gt;"[,
+ "&lt;value1&gt;"],]
+ ),]
+ )
+ )
+ )</screen>
+
+ </para>
+ <para>
+ The <literal>attributes</literal> attribute to a <literal>user_type</literal> entry holds an array with any or all of the following <emphasis>&lt;form_field_type&gt;</emphasis> keys:
+ </para>
+ <important>
+ <para>
+ The reference implementation and general rule of thumb is to use the LDAP attribute name as the form field name.
+ </para>
+
+ </important>
+ <para>
+ <itemizedlist>
+ <listitem>
+ <formalpara id="form-Administrator_Guide-Attributes_Reference-auto_form_fields">
+ <title><literal>auto_form_fields</literal></title>
+ <para>
+ The <literal>auto_form_fields</literal> key holds an array of form fields that correspond with attributes for which the value is to be generated automatically, using an API call.
+ </para>
+
+ </formalpara>
+ <para>
+ The key name for each key =&gt; value pair indicates the form field name for which the value is to be generated automatically.
+ </para>
+ <para>
+ Each array key corresponds with a user attribute name, and it's value is an array containing the name of the form fields for which the value to submit as part of the API call.
+ </para>
+ <example id="exam-Administrator_Guide-Attributes_Reference-A_Users_displayname">
+ <title>A User's <literal>displayname</literal></title>
+ <para>
+ Provided the user type's <literal>auto_form_fields</literal> contains an array key of <literal>displayname</literal>, the array value for this key could look as follows:
+ </para>
+ <para>
+
+<screen language="PHP/PHP">Array(
+ 'auto_form_fields' =&gt; Array(
+ 'displayname' =&gt; Array(
+ 'data' =&gt; Array(
+ 'givenname',
+ 'sn'
+ ),
+ ),
+ (...)
+ ),
+ (...)
+ );</screen>
+
+ </para>
+ <para>
+ This indicates to the client that a form field named 'displayname' is to be populated with the information contained within the form fields named 'givenname' and 'sn'.
+ </para>
+ <para>
+ If the client is capable of doing so, it should also update the form field named 'displayname' after the values for any of the form fields named 'givenname' or 'sn' have been changed.
+ </para>
+
+ </example>
+ <para>
+ With a JSON object payload containing the values of the form fields for which the names are contained within the 'data' key, if any, the client should submit a POST request on change of these form fields, and will be returned the new value for the automatically generated form field.
+ </para>
+
+ </listitem>
+ <listitem>
+ <formalpara id="form-Administrator_Guide-Attributes_Reference-form_fields">
+ <title><literal>form_fields</literal></title>
+ <para>
+ The <literal>form_fields</literal> key holds an array of form fields that require user input.
+ </para>
+
+ </formalpara>
+ <para>
+ The key name for each key =&gt; value pair indicates the form field name for which the value is to be supplied by the user.
+ </para>
+ <para>
+ Because some attributes can be multi-valued, or have a limited list of options, each defined form field in <literal>form_fields</literal> can hold an array with additional key =&gt; value pairs illustrating the type of form field that should be used, and what format to expect the result value in.
+ </para>
+ <para>
+ <itemizedlist id="item-Administrator_Guide-Attributes_Reference-Additional_Information_in_form_fields">
+ <title>Additional Information in <literal>form_fields</literal></title>
+ <listitem>
+ <formalpara id="form-Administrator_Guide-Additional_Information_in_form_fields-maxlength">
+ <title><literal>maxlength</literal></title>
+ <para>
+ For a form field of type <xref linkend="form-Administrator_Guide-Additional_Information_in_form_fields-text" /> or type <xref linkend="form-Administrator_Guide-Additional_Information_in_form_fields-list" />, this value holds the maximum length for a given item.
+ </para>
+
+ </formalpara>
+
+ </listitem>
+ <listitem>
+ <formalpara id="form-Administrator_Guide-Additional_Information_in_form_fields-type">
+ <title><literal>type</literal></title>
+ <para>
+ The <literal>type</literal> is to indicate the type of form field. Options include;
+ </para>
+
+ </formalpara>
+ <para>
+ <itemizedlist>
+ <listitem>
+ <formalpara id="form-Administrator_Guide-Additional_Information_in_form_fields-text">
+ <title><literal>text</literal></title>
+ <para>
+ This is a regular input field of type text.
+ </para>
+
+ </formalpara>
+ <para>
+ This is the default.
+ </para>
+ <para>
+ Additional parameters for a text form field include <xref linkend="form-Administrator_Guide-Additional_Information_in_form_fields-maxlength" />.
+ </para>
+
+ </listitem>
+ <listitem>
+ <formalpara id="form-Administrator_Guide-Additional_Information_in_form_fields-list">
+ <title><literal>list</literal></title>
+ <para>
+ A form field of type <literal>list</literal> is expecting a list of text input values.
+ </para>
+
+ </formalpara>
+ <para>
+ A client web interface could choose to display a textarea with the instructions to supply one item per line, or more advanced (better) equivalents, such as an add/delete widget.
+ </para>
+ <para>
+ A client command-line interface could choose to prompt for input values until an empty value is supplied.
+ </para>
+ <para>
+ Additional parameters for a list form field include <xref linkend="form-Administrator_Guide-Additional_Information_in_form_fields-maxlength" />, which holds the maximum length of each text value in the list.
+ </para>
+
+ </listitem>
+ <listitem>
+ <formalpara id="form-Administrator_Guide-Additional_Information_in_form_fields-multiselect">
+ <title><literal>multiselect</literal></title>
+ <para>
+ This form field is a select list, where multiple options may be selected (as opposed to a <xref linkend="form-Administrator_Guide-Additional_Information_in_form_fields-select" /> list, where only one option may be selected).
+ </para>
+
+ </formalpara>
+
+ </listitem>
+ <listitem>
+ <formalpara id="form-Administrator_Guide-Additional_Information_in_form_fields-select">
+ <title><literal>select</literal></title>
+ <para>
+ This form field is a selection list, of which one option may be selected.
+ </para>
+
+ </formalpara>
+
+ </listitem>
+
+ </itemizedlist>
+
+ </para>
+
+ </listitem>
+ <!--
+<listitem>
+ <formalpara id="form-Administrator_Guide-Additional_Information_in_form_fields-value_source">
+ <title><literal>value_source</literal></title>
+ <para>
+ para
+ </para>
+
+ </formalpara>
+
+ </listitem>
+ <listitem>
+ <formalpara id="form-Administrator_Guide-Additional_Information_in_form_fields-values">
+ <title><literal>values</literal></title>
+ <para>
+ para
+ </para>
+
+ </formalpara>
+
+ </listitem>
+ // -->
+ </itemizedlist>
+
+ </para>
+
+ </listitem>
+ <listitem>
+ <formalpara id="form-Administrator_Guide-Attributes_Reference-fields">
+ <title><literal>fields</literal></title>
+ <para>
+ The <literal>fields</literal> key holds an array of form fields and values for said form fields, that are static. One example of such form fields is <literal>objectclass</literal>.
+ </para>
+
+ </formalpara>
+
+ </listitem>
+
+ </itemizedlist>
+
+ </para>
+
+ </section>
+
+
+ </section>
+
+
+</chapter>
+
diff --git a/Administrator_Guide/en-US/part-Kolab_Server.xml b/Administrator_Guide/en-US/part-Kolab_Server.xml
index a92ed4f..2612ba0 100755
--- a/Administrator_Guide/en-US/part-Kolab_Server.xml
+++ b/Administrator_Guide/en-US/part-Kolab_Server.xml
@@ -8,6 +8,7 @@
<xi:include href="Verifying_the_Installation.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="Configuring_the_Kolab_Server.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="Detailed_Kolab_Server_Overview.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="Kolab_Web_Administration_Panel.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="Combating_Spam.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
</part>
diff --git a/Installation_Guide/en-US/Kolab_Server_First_Login.xml b/Installation_Guide/en-US/Kolab_Server_First_Login.xml
index 22b50e9..ae9ca56 100644
--- a/Installation_Guide/en-US/Kolab_Server_First_Login.xml
+++ b/Installation_Guide/en-US/Kolab_Server_First_Login.xml
@@ -34,10 +34,29 @@
<formalpara id="form-Community_Installation_Guide-Troubleshooting-Cannot_Supply_Mail_andor_Alternative_Mail_Addresses_for_the_User">
<title>Cannot Supply Mail and/or Alternative Mail Addresses for the User</title>
<para>
- Set <literal>auto_fields_admin_rw</literal> to <literal>True</literal> in section <literal>[kolab_wap]</literal> in <filename>/etc/kolab/kolab.conf</filename> and log out and back in to the Kolab Web Administration Panel.
+ The quick and easy way out is to set <literal>auto_fields_admin_rw</literal> to <literal>True</literal> in section <literal>[kolab_wap]</literal> in <filename>/etc/kolab/kolab.conf</filename> and log out and back in to the Kolab Web Administration Panel.
</para>
</formalpara>
+ <para>
+ This course of action implies you are not seeking to employ a recipient policy to the Kolab user accounts.
+ </para>
+ <para>
+ For a more sustainable approach, and greater flexibility, please consider the approach outlined in <xref linkend="form-Community_Installation_Guide-Troubleshooting-Edit_user_types" />.
+ </para>
+ <formalpara id="form-Community_Installation_Guide-Troubleshooting-Edit_user_types">
+ <title>Edit <literal>user_types</literal></title>
+ <para>
+ The <literal>user_types</literal> table in the MySQL <literal>kolab</literal> database contains the settings to create the form fields for the <emphasis>Add User</emphasis> dialog.
+ </para>
+
+ </formalpara>
+ <para>
+ At the time of this writing, editing those form fields is a manual process executed from the console. An enhancemnt for the Kolab Web Administration Panel and API is pending, see <ulink url="https://bugzilla.kolabsys.com/show_bug.cgi?id=697">bug #697</ulink> and <ulink url="https://bugzilla.kolabsys.com/show_bug.cgi?id=678">bug #678</ulink>
+ </para>
+ <para>
+ For the procedure to edit the <literal>user_types</literal>, please refer to the Administrator Guide.
+ </para>
</section>