Page Comparison

Anchor
top top

This topic explains how to use the Shell Tool which provides command line access to the Apache framework in which XperienCentral runs. This makes it possible to manage plugins, users and website settings from outside the XperienCentral GUI. The Shell Tool works for both local installations of XperienCentral as well as cloud installations. It is an extension of the Apache Felix GoGo shell. This topic only covers the XperienCentral-specific commands that you can execute from the Shell Tool. Documentation for the Apache Felix GoGo shell itself can be found at http://felix.apache.org/documentation/subprojects/apache-felix-framework/apache-felix-framework-usage-documentation.html.Beginning in version R28, GX Software uses an XperienCentral-optimized implementation for indexing content. In XperienCentral R28, the implementation ran alongside the Apache Jackrabbit JCR index functionality. In XperienCentral versions R27 and earlier, XperienCentral used only Apache Jackrabbit for content indexing.

 In XperienCentral versions R29 and higher, the Apache Jackrabbit JCR index functionality is disabled by default. If you want to use Apache Jackrabbit with XperienCentral, follow the steps in the last section of this topic. If you do not configure XperienCentral to use Apache Jackrabbit, the following functionality does not work out-of-the-box:

• The JCR Browser
• The JCR Import/Export Tool
• Custom code which has not been rewritten to use the new search index

In This Topic

...

Updates the specified website setting with the specified value.

Syntax
wmupdatewebsitesettingvalue <hostname> <entryname> <entryvalue>

If the website setting is a checkbox, use true to select it and false to clear it.

Back to Top

Managing User Passwords from the Shell Tool

From the Shell Tool you can change user passwords. The following commands are available for doing so:

...

Finds an XperienCentral user or users. This method takes the following parameters:

Examples

wmfinduser gx.test.com john returns the user with the login name "John".

wmfinduser gx.test.com joh* returns all users whose login name begins with "joh" (John, Johan, and so forth).

wmfinduser gx.test.com /b[ao]*/ returns all users whose login name begins with "ba" and "bo" (Bart, Bob, and so forth).

...

Assigns the specified password to the specified user.

Example

wmsetpassword testuser Ut3&bP8

This command will return an error message if the password is not strong enough. See User Authorization for information on how XperienCentral enforces password strength.

...

Sets a user to an active/inactive state.

Example

wmlockunlockuser johns false

This command sets the user "JohnS" to an inactive state.

Back to Top

General Commands

...

Calls the specified service (must be registered as an OSGi bundle). The possible parameters are:

• string
• int
• boolean


Example
wmcall nl.gx.webmanager.services.upgrade.UpgradeService upgrade true

...

Truncates the specified list of XperienCentral tables. This is sometimes necessary when you copy a database from one environment to another and want to start with a clean version of it. The tables that can be truncated are:

• wmLocalRevision
• wmLocalFullIndexStatus
• wmGlobalIndexEventQueue
• ClusterLock
• rtindex_items
• rtindex_Revision
• WM9_CLUSTER_JOURNAL
• WM9_CLUSTER_LOCAL_REVISIONS

...

Setting up the Shell Tool

Installing the Felix GoGo Extensions Plugin

The Felix Shell commands extension plugin is not installed by default — You have to install it manually. You can find the plugin in the XperienCentral SDK archive in the maven2-repository/nl/gx/webmanager/tools/webmanager-felix-shellcommands/<xperiencentral-version> directory. Add it by either copying the webmanager-felix-shellcommands-<xperiencentral version>.jar file to the <xperiencentral-root>/work/deploy directory or add it using the XperienCentral Plugins Management Console.

Configuring SSH

The Shell Tool requires SSH in order to allow access to the XperienCentral settings. To enable SSH, keys should be generated (version 2 RSA or DSA) and added to the XperienCentral SSH server configuration. You then have two options for pointing to the location of the keys:

1. Create the following folder and copy the keys to this location:
   <xperiencentral-root>/work/config/ssh/ (the name of the file should be authorized_keys2).
2. Create a directory, copy the keys into it and point to it using the Java property webmanager.config.directory=<dir>.

For security reasons, SSH is enabled by default only on the internal network and can only be accessed by localhost on the default port 7009. To change this port, the system property osgi.console.ssh should be added to the Java system properties (-Dosgi.console.ssh=localhost:<port> or -Dosgi.console.ssh=127.0.0.1:<port>). To enable access from another host, set this to -Dosgi.console.ssh=<port>.

Back to Top

Generating Keys

There are different ways to generate the keys. Creating the keys according to the steps below will enable access from Linux systems (using SSH) as well as from Windows systems using PuTTY.

Generate Key Pair

Linux machine

• Generate a key using ssh-keygen -t rsa on a Linux machine.

Windows machine

Putty KeyGen

...

Configure the Server

...

Connect from the Linux Machine

ssh -i my_key_file -p <port number> thehostname

Connect from Windows using PuTTY

• When the private key is generated via linux: Open the private key in PuTTYgen and save it as a PuTTY key. This conversion is needed because PuTTY does not accept OpenSSH keys.
• Add this PuTTY private key to the putty session configuration by loading it (if the entry is not new), adding the key to
  Connection > SSH > Auth > "Private key for authentication"
  ...and saving the configuration.
• Open the connection (to <hostname>:<port number>, (using the PuTTY private key) and log in. If a username is requested, simply press [Enter] enter since the value will be ignored. Use the password chosen as pass phrase when the key pair was generated.

Back to Top

Managing Plugins from the Shell Tool

In addition to the functionality available for managing plugins from the XperienCentral Plugins Management Console, there are equivalent commands available in the Shell Tool that you can invoke directly from the command line. To use the commands on a plugin in the Shell Tool, you must first determine the ID of a plugin by issuing the lb command in the Tomcat window. After you issue the lb command, you will see a list of the plugins and their IDs. For example:

Image Removed 

(click image to enlarge)

The following commands can be used on plugins running in XperienCentral from the Shell Tool:

...

Registers services that each component within the bundle exposes if all required service dependencies are available. For each component, at the very least a component service is registered. Usage:

wmstart [id]

where [id] is the plugin identifier.

...

Stops all services registered by the component. Usage

wmstop [id]

where [id] is the plugin identifier.

...

Updates the plugin to a newer version. If a problem is encountered during the update, the plugin is automatically rolled back to the existing version. The following describes a typical plugin update scenario:

...

Removes all content that was created during and after the installation of the plugin. Usage:

wmpurge [id]

where [id] is the plugin identifier.

...

Removes all content that was created during the installation of the plugin. Usage:

wmuninstall [id]

where [id] is the plugin identifier.

Back to Top

Managing Website Settings from the Shell Tool

From the Shell Tool, you can modify website settings. The settings are the same ones that you can configure/modify using the XperienCentral Setup Tool. The commands below are available for doing so. The following parameters can be used in the commands:

...

Website Commands

...

Adds a configuration value to an entry.

Syntax
wmaddconfigvalue <defname.setname.entryname> <entryvalue>

...

Adds a value to the specified website setting.

Syntax
wmaddwebsitesettingvalue <hostname> <entryname> <entryvalue>

...

Returns the value(s) of the specified configuration setting.

Syntax
wmfindconfigvalue <config set definition> <entryname>

<defname> and <setname> are optional. You can use wildcards in the <entryname> parameter. Searching for "*" returns all configuration entries and their options for all channels.

Examples

...

wmfindconfigvalue DEFAULT backend_hostname

 
wmfindconfigvalue <entryname (wildcard)>
returns entryname from DEFAULT configset

wmfindconfigvalue backend_hostname

...

Retrieves the value of the specified website setting.

Syntax
wmfindwebsitesettingvalue <hostname> <entryname>

...

Removes the specified value from the specified configuration setting.

Syntax
wmremoveconfigvalue <defname.setname.entryname> <index>


...

Updates the specified configuration setting with the specified value(s).

Syntax
wmupdateconfigvalue <defname.setname.entryname> <entryvalue>

If <entryvalue> is not specified, the website setting will be updated with its default value. If the website can have multiple values, use <index> to specify which entry to update. If the website setting is a checkbox, use true to select it and false to clear it.

...

Advantages of the XperienCentral JCR Index

The XperienCentral JCR index stores its index in the database instead of in files on disk. The major advantage of this approach is that the index can be reused by all nodes in the cluster, without the need re-index when a new node is added to the cluster. There is only one index with the database-based index which means that errors caused by a mismatch between the different indices on the nodes in the cluster can no longer occur with the new index. Finally, since the index is stored in the same database as the content to which it applies, there is no longer a need to re-index after copying an environment by restoring a backup.

Database Tables

The JCR index stores its index in two tables prefixed by wmJcrIndex; wmJcrIndexNodes and wmJcrIndexProperties. The wmJcrIndexNodes table stores the most important metadata for nodes stored in the JCR, for example the UUID, name and nodetype. The wmJcrIndexProperties stores some of the properties of these nodes and refers to the node the property belongs to in the UUID column.

Indexing

The JCR index is built automatically. Several mechanisms are in place to ensure the index is up-to-date.

Initial Index

When a new XperienCentral installation is started or an existing version lower than R28 is started, the JCR index will be built by the webmanager-jcrindex-bundle. When this bundle starts, it checks to see whether there are any records in the index tables. If not, it starts indexing automatically. This initial indexing shows the following warning messages in the log:

Initializing JCR index...
Added 5000 records to the JCR index
Added 10000 records to the JCR index
...
Finished initializing JCR index of 12425 nodes in 13253 ms

Quick Scan Task

To prevent inconsistencies in the JCR index, a "quick scan" task runs every 5 minutes. This task verifies that the number of nodes in the JCR index matches the number of nodes in the JCR. This is a very simple and cost-effective way to tell whether the index is up-to-date. Each time a mismatch is detected, a internal counter is incremented by 1. Only when 12 subsequent checks detect a mismatch (which takes approximately one hour) is the index is considered to be inconsistent which then leads to the "check and repair" task being executed.  The reason for this is that a mismatch between the index and the actual number of nodes in the JCR may appear to be in a consistent state when the checker runs at the exact moment that a JCR node is being added or removed. The probability that this can happen 12 times in a row however is very small. The "quick scan" task logs the following warning message when the JCR index is considered to be inconsistent:

JCR Index is out of sync: 835203 bundles but 835204 records in the index

Check and Repair Task

The check and repair task kicks in when the JCR index is considered to be inconsistent (see Quick Scan Task above). This task consists of two stages; the "check and repair missing records" stage and the "check and repair obsolete records" stage. The first stage loops over all nodes in the JCR and verifies that a corresponding record is available in the JCR index. If not, it appends the record to the index and logs a warning message similar to the following:

JCR index is missing record for uuid 0005781c-7689-4d48-8dfc-ecdc7a25a4ba
Adding missing record 0005781c-7689-4d48-8dfc-ecdc7a25a4ba to the JCR index

In the second stage, the task loops over all records in the JCR index and verifies that the corresponding node exists in the JCR. If it does not, it removes the record from the index and logs a warning message similar to the following:

JCR index contains obsolete record for uuid 0005781c-7689-4d48-8dfc-ecdc7a25a4ba
Removing obsolete record 0005781c-7689-4d48-8dfc-ecdc7a25a4ba from the JCR index

After running both stages, the index should be consistent again.

Anchor
reindex reindex

Reindex

In some very specific circumstances, a reindex task may be triggered. A reindex task will simply repeat the initialization of the index (without first removing it) as described in the initial index explanation above. A reindex will not truncate the index before indexing. A reindex is initiated by adding an indexed property, see Indexed Properties below.

JCR Index Query Manager

The JcrIndexQueryManager interface is the primary service API for performing search queries on the index. It can be used to perform queries in the JCR on node type, properties that must match certain values and more. For complete information on the available query methods, see the XperienCentral Javadoc.

...

Indexed Properties

When queries are performed on the JcrIndexQueryManager using the property matching method, the performance of this method heavily depends on whether these properties are contained in the index or not. Properties that are stored in the wmJcrIndexProperties table of the JCR index are referred to as "indexed properties". Performing queries on those properties is fast because the query can directly operate on the corresponding property in this table. When a query is executed on properties that are not indexed, the query will be much slower because it needs to retrieve the property from the JCR first before it can check whether the property matches.

("Property matching method": JcrIndexQueryManager#getNodes(Session session, String nodeType, Map<String, Object> filterValues) )

When a property matching query is executed, the query manager will first execute a database query that filter all nodes that match the indexed properties. Subsequently it will iterate over all remaining nodes and check which ones match the non-indexed properties. If there is a large number of remaining nodes to iterate over left, executing the query may take a long time to execute. For that reason, it is strongly recommended not to execute such queries or to make these properties indexed properties. When such a time consuming query is being executed on more than 5000 results, a warning message similar to the following is logged:

Heavy filtering using non-indexed properties: 1% of 44,150 results left after filtering on: [custompagemetadata: custompagetype, custompagemetadata:traininggroupcode, custompagemetadata:language, custompagemetadata:form]

This particular message warns that the JCR index query manager needs to iterate over 44.150 nodes in the JCR, retrieve the four properties it mentions and check whether these all match the specified values. As a result of that filtering, only 1% of those 44.150 nodes is left. This warning message will be shown when filtering on non-indexed properties reduces the result by more then 85%. In other words; if the percentage shown in the warning message is smaller than 15%. Queries like these should be avoided. There are two possible ways to resolve it. Either improve the query by matching on more indexed properties so that fewer than x number of nodes (44.150 in the example above) are left to apply the non-indexed filtering on, or make (some of) the non-indexed properties indexed. How to do so is explained in the next section.

Adding an Indexed Property

Adding and removing indexed properties is supported by the JcrIndexPropertyService service API which contains methods to retrieve the indexed properties, check whether a property is indexed and to add or remove an indexed property. Adding an indexed property is fairly easy using the JcrIndexPropertyService. For example:

JcrIndexedProperty property = new JcrIndexedProperty(
   "wmamodularcontent:stringvalue",       // The fully qualified name of the node type that holds the property
   "wmamodularcontent:templateproperty",  // The fully qualified name of the property
   PropertyType.STRING                    // The type of the property, referring to one of the types in javax.jcr.PropertyType
)
propertyService.addIndexedProperty(property);

The code snippet above will append an indexed property for the property identified by wmamodularcontent:templateproperty which is a property of the node type wmamodularcontent:stringvalue and is of type STRING.

Removing an Indexed Property

An indexed property can be removed simply using JcrIndexPropertyService#removeIndexedProperty with an instance of JcrIndexedProperty using the same arguments used to add the property. No reindex is performed after removing an indexed property.

...

Configuring Apache Jackrabbit

To enable the Apache Jackrabbit, for example to use the JCR Browser, you must make a few configuration changes to your deployment. Follow these steps:

1. Stop XperienCentral.
2. Open the file <wm-root>/work/<jcr directory>/repository.xml in a text editor.

3. Add the following declarations to the <Workspace></Workspace> section:
   
   

   Code Block
   theme Eclipse
   <SearchIndex class="org.apache.jackrabbit.core.query.lucene.SearchIndex"> <param name="path" value="${wsp.home}/index" /> <param name="respectDocumentOrder" value="false" /> <param name="useCompoundFile" value="true" /> <param name="minMergeDocs" value="100" /> <param name="volatileIdleTime" value="3" /> <param name="maxMergeDocs" value="100000" /> <param name="mergeFactor" value="100" /><!-- old: 10 --> <param name="bufferSize" value="100" /><!-- old: 10 --> <param name="cacheSize" value="100000" /><!-- old: 1000 --> <param name="forceConsistencyCheck" value="false" /> <param name="autoRepair" value="true" /> <param name="onWorkspaceInconsistency" value="log" /> </SearchIndex>

   
   
   

4. Add the following declarations to the <Versioning></Versioning> section:
   
   
   

   Code Block
   theme Eclipse
   <SearchIndex class="org.apache.jackrabbit.core.query.lucene.SearchIndex"> <param name="path" value="${rep.home}/repository/index" /> <param name="respectDocumentOrder" value="false" /> <param name="useCompoundFile" value="true" /> <param name="minMergeDocs" value="100" /> <param name="volatileIdleTime" value="3" /> <param name="maxMergeDocs" value="100000" /> <param name="mergeFactor" value="100" /><!-- old: 10 --> <param name="bufferSize" value="100" /><!-- old: 10 --> <param name="cacheSize" value="100000" /><!-- old: 1000 --> <param name="forceConsistencyCheck" value="false" /> <param name="autoRepair" value="true" /> <param name="onWorkspaceInconsistency" value="log" /> </SearchIndex>

   
   
   

5. Save repository.xml.
6. Delete the directory <wm-root>/work/jcr/repository.
7. Restart XperienCentral. The Apache Jackrabbit JCR index will be built.

Back to Top