[gatein-commits] gatein SVN: r9147 - epp/docs/branches/6.0/Admin_Guide/en-US.

Author: rdickens Date: 2013-02-13 20:39:24 -0500 (Wed, 13 Feb 2013) New Revision: 9147 Modified: epp/docs/branches/6.0/Admin_Guide/en-US/chapter-4-Management_Extensions.xml Log: Review and editing, with grammatical corrections and some DocBook tags changed. Modified: epp/docs/branches/6.0/Admin_Guide/en-US/chapter-4-Management_Extensions.xml =================================================================== --- epp/docs/branches/6.0/Admin_Guide/en-US/chapter-4-Management_Extensions.xml 2013-02-13 20:34:04 UTC (rev 9146) +++ epp/docs/branches/6.0/Admin_Guide/en-US/chapter-4-Management_Extensions.xml 2013-02-14 01:39:24 UTC (rev 9147) @@ -5,15 +5,9 @@ ]> <chapter id="sid-8094332_GateInManagement-ManagementExtensions"> <title>Management Extensions</title> - <para>The following management extensions supported in the portal are:</para> - <itemizedlist> - <listitem> - <para>MOP Management Extension</para> - </listitem> - </itemizedlist> <section id="sid-8094332_GateInManagement-MOPManagementExtension"> <title>MOP Management Extension</title> - <para>The MOP management extension registers the &apos;mop&apos; managed component which is responsible for managing pages, navigation, and site layout. It primarily supports exporting and importing this data through the export-resource and import-resource operations. It also supports the read-config-as-xml operation to expose the portal meta data as xml.</para> + <para>The MOP management extension registers the &apos;mop&apos; managed component which is responsible for managing pages, navigation, and site layout. It primarily supports exporting and importing this data through the <systemitem>export-resource</systemitem> and <systemitem>import-resource</systemitem> operations. It also supports the read-config-as-xml operation to expose the portal meta data as XML.</para> <section id="sid-8094332_GateInManagement-Operationsxx"> <title><remark>BZ#794408 </remark>Operations</title> <section id="sid-8094332_GateInManagement-readconfigasxml"> @@ -21,9 +15,9 @@ <para> The <code>read-config-as-xml</code> - operation can only be executed on the site layout, pages, and navigation managed resources. The xml format returned is that of which is defined in by the + operation can only be executed on the site layout, pages, and navigation managed resources. The XML format returned is defined by the <ulink url="http://www.gatein.org/xml/ns/">gatein-objects</ulink... - xsd. This means that these resources are exposed in the same format as what a portal extension would accept for importing data into the portal. + XSD. These resources are exposed in the same format a portal extension would accept for importing data into the portal. </para> </section> <section id="sid-8094332_GateInManagement-exportresource"> @@ -31,7 +25,7 @@ <para> The <code>export-resource</code> - operation can be executed on any resource of the MOP extension (including the mop component itself). Since the management system recursively searches for all sub-resources that have export-resource defined (which they are defined at the site layout, page, and navigation level), exports can be very granular. + operation can be executed on any resource of the MOP extension (including the <systemitem>mop</systemitem> component itself). Since the management system recursively searches for all sub-resources that have export-resource defined (which is defined at the site layout, page, and navigation level), exports can be very granular. </para> <para>This operation is accessed through the portal using the <application>Import/Export Site</application> tool. For more information about this tool, refer to the <citetitle>Import and Export</citetitle> section in the <citetitle>User Guide</citetitle>.</para> </section> @@ -40,9 +34,9 @@ <para> The <code>import-resource</code> - operation can only be executed at the mop component (root managed resource of the mop extension). This is because the exported zip file contains the path information (like site type and site name). So executing an + operation can only be executed at the mop component (root managed resource of the mop extension). This is because the exported Zip file contains path information (like site type and site name). So executing an <code>import-resource</code> - operation on a group site, when the zip contains data from a portal site, does not make sense. + operation on a group site, when the Zip contains data from a portal site, does not make sense. </para> <para>This operation is accessed through the portal using the <application>Import/Export Site</application> tool. For more information about this tool, refer to the <citetitle>Import and Export</citetitle> section in the <citetitle>User Guide</citetitle>.</para> <para> @@ -57,7 +51,7 @@ <term>Conserve</term> <listitem> <para> - Import data only if no artifacts exist for that site. For example if one page exists for site &apos;classic&apos;, nothing will be imported. + Import data only if no artifacts exist for that site. For example if one page exists for site <citetitle>classic</citetitle>, nothing will be imported. </para> </listitem> @@ -84,9 +78,9 @@ <term>Overwrite</term> <listitem> <para> - Delete all data for that artifact of the site, import new data. For example if the zip file only contains pages for site classic, then + Delete all data for that artifact of the site, then import new data. For example if the Zip file only contains pages for site <citetitle>classic</citetitle>, then - all pages for that site are deleted and imported. + all pages for that site are deleted and the contents of the Zip file imported. </para> </listitem> @@ -97,59 +91,54 @@ <section id="sid-8094332_GateInManagement-PathTemplatesx"> <title>Path Templates</title> <para>Below are the list of path template variables defined in the MOP management extension. These path template variables are used for filtering during export.</para> - <itemizedlist> - <listitem> - <para> - <code>site-type</code> - - These are the site types of the portal to include or exclude. Available values are: + <variablelist> + <title>Path template variables</title> + <varlistentry> + <term>site-type</term> + <listitem> + <para> + These are the site types of the portal to include or exclude. Available values are: <code>portal</code> , <code>group</code> , and - <code>user</code> - . - </para> - </listitem> - <listitem> - <para> - <code>site-name</code> - - The sites to include or exclude. Examples could be - <code>classic</code> - and - <code>/platform/administrators</code> - . - </para> - </listitem> - <listitem> - <para> - <code>site-layout</code> - - The name of the site layout depending on the site type. Available values are: - <code>portal</code> - , - <code>group</code> - , - <code>user</code> - . - </para> - </listitem> - <listitem> - <para> - <code>page-name</code> - - The name of the page(s) to include or exclude. - </para> - </listitem> - <listitem> - <para> - <code>nav-uri</code> - - The URI of the navigation node to include or exclude. - </para> - </listitem> - </itemizedlist> + <code>user</code>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>site-name</term> + <listitem> + <para> + The sites to include or exclude. Examples could be <code>classic</code> and <code>/platform/administrators</code>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>site-layout</term> + <listitem> + <para> + The name of the site layout depending on the site type. Available values are: <code>portal</code>, <code>group</code>, <code>user</code>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>page-name</term> + <listitem> + <para> + The name of the page(s) to include or exclude. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>nav-uri</term> + <listitem> + <para> + The URI of the navigation node to include or exclude. + </para> + </listitem> + </varlistentry> + </variablelist> </section> <section id="sid-8094332_GateInManagement-RESTAPI"> <title>REST API</title> @@ -168,7 +157,7 @@ <section id="sid-8094332_GateInManagement-MOPComponentResource"> <title>MOP Component Resource</title> <para> - The mop managed component resource (root managed resource) is the only resource that accepts the + The <systemitem>mop</systemitem> managed component resource (root managed resource) is the only resource that accepts the <code>import-resource</code> operation. </para> @@ -181,18 +170,18 @@ </example> <example> <title>HTTP Response</title> - <programlisting>HTTP/1.1 200 OK</programlisting> + <screen>HTTP/1.1 200 OK</screen> </example> </section> <section id="sid-8094332_GateInManagement-SiteLayoutResource"> <title>Site Layout Resource</title> <para> - The site layout resource represents the site layout of the portal. It&apos;s the data defined in the - <emphasis role="strong">portal.xml</emphasis> + The site layout resource represents the site layout of the portal. It is the data defined in the + <filename>portal.xml</filename> , - <emphasis role="strong">group.xml</emphasis> + <filename>group.xml</filename> , and - <emphasis role="strong">user.xml</emphasis> + <filename>user.xml</filename> files (depending on site type) used in portal extensions to configure data. </para> <example> @@ -201,18 +190,18 @@ </example> <section id="sid-8094332_GateInManagement-readconfigasxmlx"> <title>config-as-xml</title> - <para>Example of reading the site layout as xml for site classic.</para> + <para>Example of reading the site layout as XML for site classic.</para> <example> <title>HTTP Request</title> - <programlisting>GET /mop/portalsites/classic/portal.xml + <screen>GET /mop/portalsites/classic/portal.xml or -GET /mop/portalsites/classic/portal?op=read-config-as-xml</programlisting> +GET /mop/portalsites/classic/portal?op=read-config-as-xml</screen> </example> <example> <title>HTTP Response</title> - <programlisting>HTTP/1.1 200 OK + <screen>HTTP/1.1 200 OK Content-Type: application/xml &lt;portal-config&gt; @@ -221,7 +210,7 @@ &lt;description&gt;GateIn default portal&lt;/description&gt; &lt;locale&gt;en&lt;/locale&gt; ... -&lt;/portal-config&gt;</programlisting> +&lt;/portal-config&gt;</screen> </example> </section> <section id="sid-8094332_GateInManagement-exportresourcex"> @@ -229,42 +218,42 @@ <para>Example of exporting the site layout for site classic.</para> <example> <title>HTTP Request</title> - <programlisting>GET /mop/portalsites/classic/portal.zip + <screen>GET /mop/portalsites/classic/portal.zip or -GET /mop/portalsites/classic/portal?op=export-resource</programlisting> +GET /mop/portalsites/classic/portal?op=export-resource</screen> </example> <example> <title>HTTP Response</title> - <programlisting>HTTP/1.1 200 OK + <screen>HTTP/1.1 200 OK Content-Type: application/zip -[binary data]</programlisting> +[binary data]</screen> </example> </section> </section> <section id="sid-8094332_GateInManagement-PagesResource"> <title>Pages Resource</title> - <para>The pages resource represents the pages of the portal. It&apos;s the data defined in the pages.xml used in portal extensions to configure data.</para> + <para>The pages resource represents the pages of the portal. It is the data defined in the <filename>pages.xml</filename> used in portal extensions to configure data.</para> <example> <title>URL</title> <programlisting>URL: /mop/{site-type}sites/{site-name}/pages/{page-name}</programlisting> </example> <section id="sid-8094332_GateInManagement-readconfigasxmlxx"> <title>config-as-xml</title> - <para>Example of reading all pages as xml for site classic.</para> + <para>Example of reading all pages as XML for site <citetitle>classic</citetitle>.</para> <example> <title>HTTP Request</title> - <programlisting>GET /mop/portalsites/classic/pages.xml + <screen>GET /mop/portalsites/classic/pages.xml or -GET /mop/portalsites/classic/pages?op=read-config-as-xml</programlisting> +GET /mop/portalsites/classic/pages?op=read-config-as-xml</screen> </example> <example> <title>HTTP Response</title> - <programlisting>HTTP/1.1 200 OK + <screen>HTTP/1.1 200 OK Content-Type: application/xml &lt;page-set&gt; @@ -276,20 +265,20 @@ &lt;show-max-window&gt;false&lt;/show-max-window&gt; &lt;portlet-application&gt; ... -&lt;/page-set&gt;</programlisting> +&lt;/page-set&gt;</screen> </example> - <para>Example of reading the homepage as xml for site classic.</para> + <para>Example of reading the homepage as XML for site <citetitle>classic</citetitle>.</para> <example> <title>HTTP Request</title> - <programlisting>GET /mop/portalsites/classic/pages/homepage.xml + <screen>GET /mop/portalsites/classic/pages/homepage.xml or -GET /mop/portalsites/classic/pages/homepage?op=read-config-as-xml</programlisting> +GET /mop/portalsites/classic/pages/homepage?op=read-config-as-xml</screen> </example> <example> <title>HTTP Response</title> - <programlisting>HTTP/1.1 200 OK + <screen>HTTP/1.1 200 OK Content-Type: application/xml &lt;page-set&gt; @@ -301,50 +290,50 @@ &lt;show-max-window&gt;false&lt;/show-max-window&gt; &lt;portlet-application&gt; ... -&lt;/page-set&gt;</programlisting> +&lt;/page-set&gt;</screen> </example> </section> <section id="sid-8094332_GateInManagement-exportresourcexx"> <title>export-resource</title> - <para>Example of exporting all pages of site classic.</para> + <para>Example of exporting all pages of site <citetitle>classic</citetitle>.</para> <example> <title>HTTP Request</title> - <programlisting>GET /mop/portalsites/classic/pages.zip + <screen>GET /mop/portalsites/classic/pages.zip or -GET /mop/portalsites/classic/pages?op=export-resource</programlisting> +GET /mop/portalsites/classic/pages?op=export-resource</screen> </example> <example> <title>HTTP Response</title> - <programlisting>HTTP/1.1 200 OK + <screen>HTTP/1.1 200 OK Content-Type: application/zip -[binary data]</programlisting> +[binary data]</screen> </example> </section> </section> <section id="sid-8094332_GateInManagement-NavigationResource"> <title>Navigation Resource</title> - <para>The navigation resource represents the navigation of the portal. It&apos;s the data defined in the navigation.xml used in portal extensions to configure data.</para> + <para>The navigation resource represents the navigation of the portal. It is the data defined in the <filename>navigation.xml</filename> used in portal extensions to configure data.</para> <example> <title>URL</title> <programlisting>URL: /mop/{site-type}sites/{site-name}/navigation/{nav-uri}</programlisting> </example> <section id="sid-8094332_GateInManagement-readconfigasxmlxxx"> <title>config-as-xml</title> - <para>Example of reading all navigation as xml for site classic.</para> + <para>Example of reading all navigation as XML for site <citetitle>classic</citetitle>.</para> <example> <title>HTTP Request</title> - <programlisting>GET /mop/portalsites/classic/navigation.xml + <screen>GET /mop/portalsites/classic/navigation.xml or -GET /mop/portalsites/classic/navigation?op=read-config-as-xml</programlisting> +GET /mop/portalsites/classic/navigation?op=read-config-as-xml</screen> </example> <example> <title>HTTP Response</title> - <programlisting>HTTP/1.1 200 OK + <screen>HTTP/1.1 200 OK Content-Type: application/xml &lt;node-navigation&gt; @@ -360,20 +349,20 @@ &lt;node&gt; &lt;name&gt;sitemap&lt;/name&gt; ... -&lt;/node-navigation&gt;</programlisting> +&lt;/node-navigation&gt;</screen> </example> - <para>Example of reading the home node as xml for site classic.</para> + <para>Example of reading the home node as XML for site <citetitle>classic</citetitle>.</para> <example> <title>HTTP Request</title> - <programlisting>GET /mop/portalsites/classic/navigation/home.xml + <screen>GET /mop/portalsites/classic/navigation/home.xml or -GET /mop/portalsites/classic/navigation/home?op=read-config-as-xml</programlisting> +GET /mop/portalsites/classic/navigation/home?op=read-config-as-xml</screen> </example> <example> <title>HTTP Response</title> - <programlisting>HTTP/1.1 200 OK + <screen>HTTP/1.1 200 OK Content-Type: application/xml &lt;node-navigation&gt; @@ -388,26 +377,26 @@ &lt;page-reference&gt;portal::classic::homepage&lt;/page-reference&gt; &lt;/node&gt; &lt;/page-nodes&gt; -&lt;/node-navigation&gt;</programlisting> +&lt;/node-navigation&gt;</screen> </example> </section> <section id="sid-8094332_GateInManagement-exportresourcexxx"> <title>export-resource</title> - <para>Example of exporting all navigation of site classic.</para> + <para>Example of exporting all navigation of site <citetitle>classic</citetitle>.</para> <example> <title>HTTP Request</title> - <programlisting>GET /mop/portalsites/classic/navigation.zip + <screen>GET /mop/portalsites/classic/navigation.zip or -GET /mop/portalsites/classic/navigation?op=export-resource</programlisting> +GET /mop/portalsites/classic/navigation?op=export-resource</screen> </example> <example> <title>HTTP Response</title> - <programlisting>HTTP/1.1 200 OK + <screen>HTTP/1.1 200 OK Content-Type: application/zip -[binary data]</programlisting> +[binary data]</screen> </example> </section> </section> @@ -421,16 +410,19 @@ operation. The filter attribute is a multi-value attribute that is passed as request parameters of the HTTP request. </para> <note> - <title>Note</title> <para>You can either include multiple filter parameters (?filter=foo:bar&amp;filter=baz:foo-bar) or separate via &apos;;&apos; character (?filter=foo:bar;baz:foo-bar)</para> </note> <example> <title>Export only registry and pageManagement navigation nodes</title> - <programlisting>GET /mop/groupsites/platform/administrators/navigation.zip?filter=nav-uri:/administration/registry,/administration/pageManagement</programlisting> + <para> + <command>GET /mop/groupsites/platform/administrators/navigation.zip?filter=nav-uri:/administration/registry,/administration/pageManagement</command> + </para> </example> <example> - <title>Export all site types but user and group</title> - <programlisting>GET /mop.zip?filter=site-type:!user,group</programlisting> + <title>Export all site types but <systemitem>user</systemitem> and <systemitem>group</systemitem></title> + <para> + <command>GET /mop.zip?filter=site-type:!user,group</command> + </para> </example> </section> </section> @@ -439,17 +431,17 @@ <para>The commands included in the management component provide us the tools to perform management operations on these MOP artifacts: site layout, pages, and navigation.</para> <section id="sid-8094332_GateInManagement-ResourcePaths"> <title>Resource Paths</title> - <para>The paths of the MOP resources are exactly the same as the REST URL&apos;s (of course without the URL syntax). For example the path of the homepage for the classic site would be:</para> + <para>The paths of the MOP resources are exactly the same as the REST URLs (without the URL syntax). For example the path of the homepage for the <citetitle>classic</citetitle> site would be:</para> <example> <title>Example</title> - <programlisting>[ /]% cd /mop/portalsites/classic/pages/homepage + <screen>[ /]% cd /mop/portalsites/classic/pages/homepage [homepage]% pwd -/mop/portalsites/classic/pages/homepage</programlisting> +/mop/portalsites/classic/pages/homepage</screen> </example> <note> <title>Note</title> - <para>All resources/paths can be autocompleted by hitting the tab key.</para> + <para>All resources/paths can be autocompleted by pressing the <systemitem>Tab</systemitem> key.</para> </note> </section> <section id="sid-8094332_GateInManagement-ExportandFilteringx"> @@ -467,25 +459,33 @@ </para> <example> <title>Export all portal site types</title> - <programlisting>export --file /tmp/mop.zip --filter site-type:portal /mop</programlisting> + <para> + <command>export --file /tmp/mop.zip --filter site-type:portal /mop</command> + </para> </example> <example> <title>Export all sites types but user</title> - <programlisting>export --file /tmp/mop.zip --filter site-type:!user /mop</programlisting> + <para> + <command>export --file /tmp/mop.zip --filter site-type:!user /mop</command> + </para> </example> <para>The option can be specified multiple times for multiple values.</para> <example> <title>Export only the /platform/administrators group site</title> - <programlisting>export --file /tmp/mop.zip --filter site-type:group --filter site-name:/platform/administrators /mop</programlisting> + <para> + <command>export --file /tmp/mop.zip --filter site-type:group --filter site-name:/platform/administrators /mop</command> + </para> </example> <para> - Also as discussed in the Path Templates section in this document, the filter attribute can separate different path templates by the + Also as discussed in the <citetitle>Path Templates</citetitle> section, the filter attribute can separate different path templates by the <code>;</code> character. </para> <example> - <title>Export only pages named homepage, navigation named home for site classic</title> - <programlisting>export --file /tmp/classic.zip --filter page-name:homepage;nav-uri:home /mop/portalsites/classic</programlisting> + <title>Export only pages named homepage, navigation named home for site <citetitle>classic</citetitle></title> + <para> + <command>export --file /tmp/classic.zip --filter page-name:homepage;nav-uri:home /mop/portalsites/classic</command> + </para> </example> <important> <title>Important</title> @@ -502,9 +502,11 @@ </para> <example> <title>Export MOP artifacts</title> - <programlisting>$ scp -P 2000 &apos;root@example.org:portal:/mop/portalsites/classic&apos; classic.zip -$ scp -P 2000 &apos;root@example.org:portal:/mop/portalsites/classic/pages/homepage&apos; homepage.zip -$ scp -P 2000 &apos;root@example.org:portal:/mop&apos; mop.zip</programlisting> + <para> + <screen>$ scp -P 2000 &apos;root@example.org:portal:/mop/portalsites/classic&apos; classic.zip + $ scp -P 2000 &apos;root@example.org:portal:/mop/portalsites/classic/pages/homepage&apos; homepage.zip + $ scp -P 2000 &apos;root@example.org:portal:/mop&apos; mop.zip</screen> + </para> </example> <para> The @@ -515,9 +517,11 @@ </para> <example> <title>Import MOP artifacts</title> - <programlisting>$ scp -P 2000 classic.zip &apos;root@example.org:portal:/mop&apos; -$ scp -P 2000 homepage.zip &apos;root@example.org:portal:/mop?importMode=overwrite&apos; -$ scp -P 2000 mop.zip &apos;root@example.org:portal:/mop&apos;</programlisting> + <para> + <screen>$ scp -P 2000 classic.zip &apos;root@example.org:portal:/mop&apos; + $ scp -P 2000 homepage.zip &apos;root@example.org:portal:/mop?importMode=overwrite&apos; + $ scp -P 2000 mop.zip &apos;root@example.org:portal:/mop&apos;</screen> + </para> </example> </section> </section>