Author: thomas.heute(a)jboss.com Date: 2007-09-12 07:37:29 -0400 (Wed, 12 Sep 2007) New Revision: 8241 Modified: docs/trunk/referenceGuide/en/modules/identityportlets.xml docs/trunk/referenceGuide/en/modules/xmldescriptors.xml Log: Doc update Modified: docs/trunk/referenceGuide/en/modules/identityportlets.xml =================================================================== --- docs/trunk/referenceGuide/en/modules/identityportlets.xml 2007-09-12 10:34:10 UTC (rev 8240) +++ docs/trunk/referenceGuide/en/modules/identityportlets.xml 2007-09-12 11:37:29 UTC (rev 8241) @@ -10,41 +10,46 @@ <sect1 id="identity_portlet_introduction"> <title>Introduction</title> <para> - Since JBoss Portal 2.6.2 two new Identity User Portlets are + Since JBoss Portal 2.6.2 two new Identity Portlets are shipped by default: <itemizedlist> <listitem> <para>The User Portlet</para> </listitem> <listitem> - <para>The User Management Portlet</para> + <para>The Identity Management Portlet</para> </listitem> </itemizedlist> As the names indicate - the User Portlet is responsible for - actions related to the end user. Whereas the User Management + actions related to the end user. Whereas the Identity Management Portlet contains all the functionality for managing users and roles. </para> <warning> - The Identity Portlets will evolve over time! Therefore usage and - configuration can change. + The identity portlets will evolve over time, therefore usage and + configuration might change. </warning> <sect2> <title>Features</title> <para> - The Identity User Portlets provide features like: + The identity portlets provide the following features: <itemizedlist> <listitem> - <para>Captcha support</para> + <para>Email verification: The users can receive an email with a link on which they must click to confirm the + creation of the new account. (Disabled by default,see <xref linkend="identity_portlet_configuration_jbpm"/>)</para> </listitem> <listitem> - <para>Lost password</para> + <para>Captcha support: The users are prompted to copy letters from a deformed image. (Enabled by default, see <xref linkend="identity_portlet_configuration_captcha"/>)</para> </listitem> <listitem> - <para>jBPM based user registration</para> + <para>Lost password: The users can receive a new password by email, any user with access to the admin portlet can also reset another user's password and send the new one by email in one click. (Disabled by default, see <xref linkend="identity_portlet_configuration_lost_password"/>)</para> </listitem> <listitem> - <para>User and role management</para> + <para>jBPM based user registration: Several business processes are available out of the box (this includes administration approval), this can + be extended to custom ones. See <xref linkend="identity_portlet_configuration_jbpm"/>.</para> </listitem> + <listitem> + <para>User and role management: Ability for the administrator to add and edit users as well as adding, </para> + </listitem> </itemizedlist> </para> </sect2> @@ -58,19 +63,17 @@ <sect2 id="identity_portlet_configuration_captcha"> <title>Captcha support</title> <para> - CAPTCHA is an acronym for Completely Automated Public - Turing test to tell Computers and Humans Apart. They are + CAPTCHA is an acronym for <literal>Completely Automated Public + Turing test to tell Computers and Humans Apart</literal>. This is providing a mechanism to prevent automated programs - (like bots) of using different services. The User - Portlet uses JCaptcha for providing a challenge-response - test. + from using different services. The User + Portlet uses JCaptcha to provide a challenge-response. </para> - <note> - By default the captcha service needs a XServer to + <note><para>By default the captcha service needs a XServer to generate the images. For using the captcha service without a XServer make sure you run the jvm with the following option: - <programlisting>-Djava.awt.headless=true</programlisting> + <programlisting>-Djava.awt.headless=true</programlisting></para> </note> <para></para> <mediaobject> @@ -84,8 +87,8 @@ </mediaobject> <para> The captcha support can be enabled by changing the - portlet preference 'captcha' to 'true'. If enabling - captcha it will be used for the registration and lost + portlet preference 'captcha' to 'true'. If enabled, + captcha will be used for the registration and lost password action. </para> <programlisting><![CDATA[... @@ -109,7 +112,7 @@ his password by entering his username. </para> <note> - This feature requires a properly configured MailModule. + This feature requires a properly configured MailModule. See <xref linkend="emailConfiguration"/>. </note> <para></para> <mediaobject> @@ -174,21 +177,19 @@ subscription modes: <itemizedlist> <listitem> - <para> - Automatic subscription (no jBPM required) - </para> + <para>Automatic subscription (no jBPM required), the users can register and directly login.</para> </listitem> <listitem> - <para>E-Mail validation</para> + <para>E-Mail validation, the users need to click on a link sent by email before being able to login.</para> </listitem> <listitem> - <para>E-Mail validation and approval</para> + <para>E-Mail validation and admin approval, the users need to validate their email, then an admin needs to + approve the newly created account.</para> </listitem> </itemizedlist> </para> <note> - It is not recommended to change the subscription mode - while runtime. + Defining the subscription mode has to be done in the configuration file as explained here: <xref linkend="identity_portlet_configuration_file"/>. It is not recommended to change the subscription mode during runtime. </note> <para></para> <mediaobject> @@ -209,7 +210,7 @@ <para> The Identity Portlets use some metadata which can be easily changed in the main configuration file, which is - shown in the following listing: + located at <literal>jboss-portal.sar/portal-identity.sar/conf/identity-ui-configuration.xml</literal> as shown here: </para> <programlisting><![CDATA[<identity-ui-configuration> @@ -290,7 +291,7 @@ <emphasis role="bold"> overwrite-workflow: </emphasis> - if set to 'true' the workflow will be overwritten (default: false) + if set to 'true' the workflow will be overwritten during the next startup (default: false) </para> </listitem> <listitem> @@ -298,13 +299,13 @@ <emphasis role="bold"> email-domain: </emphasis> - e-mail domain in the validation e-mail + e-mail domain used in the validation e-mail by the template (can be anything) </para> </listitem> <listitem> <para> <emphasis role="bold">email-from:</emphasis> - e-mail from in the validation e-mail + e-mail fro field used by the validation e-mail </para> </listitem> <listitem> @@ -312,7 +313,7 @@ <emphasis role="bold"> password-generation-characters: </emphasis> - used characters for generating a random password + characters to use to generate a random password </para> </listitem> <listitem> @@ -334,7 +335,7 @@ ui-components: </emphasis> Defines the available user interface components. Take a look at the next section - for further information. + for further details. </para> </listitem> </itemizedlist> @@ -388,10 +389,12 @@ <sect2 id="identity_portlet_configuration_example1"> <title>Example 1: required fields</title> <para> - This example covers changing not required properties to - required and adding them to the registration page. + This example explains how to changed optional properties to + required properties, of course once this is done, we will also need to + add the corresponding fields in the registration page. <sbr /> - changes in <emphasis>portal-identity.sar/conf/identity-ui-configuration.xml</emphasis> + Here are the modifications in <emphasis>portal-identity.sar/conf/identity-ui-configuration.xml</emphasis>, + we simply changed the required element to true on our two fields corresponding to the given and family names. </para> <programlisting><![CDATA[<identity-ui-configuration> ... @@ -408,7 +411,8 @@ ... </identity-ui-configuration>]]></programlisting> <para> - changes in <emphasis>portal-identity.sar/portal-identity.war/WEB-INF/jsf/common/register.xhtml</emphasis> + Now that we changed those values to "required" we need to give a chance to the user to enter those + values, here are the changes done in <emphasis>portal-identity.sar/portal-identity.war/WEB-INF/jsf/common/register.xhtml</emphasis> </para> <programlisting><![CDATA[ ... @@ -425,8 +429,10 @@ <h:message for="lastname"/> ...]]></programlisting> <para> - That's it - from now on the given and familyname will be - required on registration as well in the edit profile. + That's it - from now on the given name and family name will be + required on registration. You may also want to add this piece of code on the edit profile page. + We dynamically obtain the values from the descriptor. Now if i just wanted to make them back to optional, + i would change the values only in the descriptor, letting the user enter or not those values. </para> </sect2> <sect2 id="identity_portlet_configuration_example2"> @@ -435,7 +441,8 @@ values) </title> <para> - changes in<emphasis>portal-identity.sar/conf/identity-ui-configuration.xml</emphasis> + If the data to enter is a choice instead of a free-text value, you can also define those + in the descriptor like shown here: </para> <programlisting><![CDATA[<identity-ui-configuration> ... @@ -452,9 +459,8 @@ ... </identity-ui-configuration>]]></programlisting> <para> - changes in <emphasis> - portal-identity.sar/portal-identity.war/WEB-INF/jsf/common/profile.xhtml + In portal-identity.sar/portal-identity.war/WEB-INF/jsf/common/profile.xhtml </emphasis> - change inputText to a selectOneMenu: </para> @@ -470,7 +476,7 @@ ... ]]></programlisting> <para> - localization: in e.g. + For localization, we can use the resource bundle: in e.g. <emphasis> portal-identity.sar/conf/bundles/Identity.properties </emphasis> @@ -479,21 +485,22 @@ </para> <programlisting><![CDATA[ ... -IDENTIY_DYNAMIC_VALUE_BOARD=localized snowboarding -IDENTIY_DYNAMIC_VALUE_SKI=localized skiing -IDENTIY_DYNAMIC_VALUE_SLEDGE=localized sledging +IDENTITY_DYNAMIC_VALUE_BOARD=localized snowboarding +IDENTITY_DYNAMIC_VALUE_SKI=localized skiing +IDENTITY_DYNAMIC_VALUE_SLEDGE=localized sledging ... ]]></programlisting> <note> - If the value is not required a blank element will be - added at the top. + <para>If the value is not required a blank element will be + added at the top.</para> </note> </sect2> <sect2 id="identity_portlet_configuration_example3"> <title>Example 3: adding new properties</title> <note> Please make sure you read at least the section about - user profile configuration: <xref linkend="user_profile_configuration"/> + user profile configuration: <xref linkend="user_profile_configuration"/>, to add a new value on + the interface it also has to be defined in your model, as shown on Step 1. </note> <para> <emphasis role="bold">step 1:</emphasis> @@ -664,24 +671,23 @@ </listitem> </itemizedlist> </para> - <note> - The values of the profile-config.xml have a higher + <warning> + <para>The values of the profile-config.xml have a higher priority than the values in the user portlet configuration. That means if the 'usage' is 'mandatory' in <emphasis>profile-config.xml</emphasis> and 'required' is 'false' it will be overwritten by the - value from the profile config! - </note> + value from the profile config!</para> + </warning> </sect2> </sect1> <sect1> <title>Customizing the workflow</title> - <note>jBPM is not part of this documentation.</note> + <note><para>For more details about jBPM please read the jBPM documentation</para></note> <para> The process definitions are located in: - <emphasis>portal-identity.sar/conf/processes</emphasis>. For creating a custom workflow the custom workflow (<emphasis>custom.xml</emphasis>) can be extended. - It is not recommended to change the predefined workflow definitions. + <emphasis>portal-identity.sar/conf/processes</emphasis>. To create a custom workflow , the workflow <emphasis>custom.xml</emphasis> can be extended. </para> <para> Available variables in the business process: @@ -782,7 +788,7 @@ <programlisting><![CDATA[<process-definition> ... <state name="validate_email"> - <timer name="time_to_expire" duedate="24 hours" transition="timedOut" /> + <timer name="time_to_expire" duedate="2 days" transition="timedOut" /> </state> ... </process-definition>]]></programlisting> @@ -794,15 +800,15 @@ <sect1> <title>Disabling the Identity Portlets</title> <para> - Due to the fact that the common User portlet is still + Due to the fact that the former user portlets are still included in JBoss Portal 2.6.2 it is possible to activate it over the Portal Admin interface, by using the PortletInstances: <itemizedlist> <listitem> - <emphasis>UserPortletInstance:</emphasis> The common user portlet + <emphasis>UserPortletInstance:</emphasis> The former user portlet </listitem> <listitem> - <emphasis>RolePortletInstance:</emphasis> The common role managment portlet + <emphasis>RolePortletInstance:</emphasis> The former role managment portlet </listitem> </itemizedlist> </para> @@ -810,7 +816,8 @@ <title>Enabling the Identity Portlets</title> <para> When migrating from former versions of JBoss Portal the Identity User Portlets won't be displayed by default, - but Windows can be created on basis of the existing Portlet Instances which are by default deployed. + but Windows can be created on basis of the existing Portlet Instances which are by default deployed. (The instances + names being <literal>IdentityUserPortletInstance</literal> and <literal>IdentityAdminPortletInstance</literal>. </para> </sect2> </sect1> Modified: docs/trunk/referenceGuide/en/modules/xmldescriptors.xml =================================================================== --- docs/trunk/referenceGuide/en/modules/xmldescriptors.xml 2007-09-12 10:34:10 UTC (rev 8240) +++ docs/trunk/referenceGuide/en/modules/xmldescriptors.xml 2007-09-12 11:37:29 UTC (rev 8241) @@ -1101,7 +1101,7 @@ directory: <mediaobject> <imageobject> - <imagedata align="center" fileref="images/setup/package.gif" + <imagedata align="center" fileref="images/setup/package.png" valign="middle"/> </imageobject> </mediaobject> @@ -1110,7 +1110,7 @@ should contain the following files, that you can customize for your own Database/Connector: <mediaobject> <imageobject> - <imagedata align="center" fileref="images/setup/dsfiles.gif" + <imagedata align="center" fileref="images/setup/dsfiles.png" valign="middle"/> </imageobject> </mediaobject> @@ -1131,7 +1131,7 @@ <programlisting>build datasource</programlisting> <mediaobject> <imageobject> - <imagedata align="center" valign="middle" fileref="images/setup/build_ds.gif"/> + <imagedata align="center" valign="middle" fileref="images/setup/build_ds.png"/> </imageobject> </mediaobject> </para> @@ -1139,7 +1139,7 @@ Once complete, the datasource build should produce the following directory and file structure: <mediaobject> <imageobject> - <imagedata align="center" valign="middle" fileref="images/setup/build_ds_dir.gif"/> + <imagedata align="center" valign="middle" fileref="images/setup/build_ds_dir.png"/> </imageobject> </mediaobject> </para>