Vignette Connector

You are reading the CRX 2.3 version of Vignette Connector.

Caution

This page may be out of date for versions after CQ 5.5. It has not been tested.

The CRX Connector for Vignette V7 belongs to Day's CRX connector family. CRX is Day's Content Repository Extreme (CRX), fully implementing the Content Repository API for Java Technology (JCR). The Vignette V7 connector implements a portion of the JCR interface, enabling applications to read, search and observe changes in the Vignette V7 repository using the JCR API.

Making your Vignette repository JCR compliant consists of the following steps:

  • Installing and configuring the CRX repository used as framework for the Vignette V7 connector
  • Installing the Vignette V7 connector and the included remote access extension
  • Configuring the Vignette V7 connector

Features

The CRX Connector for Vignette V7 includes the following functionality:

  1. Read from the Vignette repository via the Vignette CMS API
  2. Execute queries on the Vignette repository
  3. Use the user accounts and access controls (ACLs) specified in the Vignette repository
  4. Observe user and content changes that occur in the Vignette repository

Supported Platforms

The connector runs on the following operation systems:

  • Windows Server 2000, 2003
  • Red Hat Enterprise Linux Advanced Server 3 and 4
  • Solaris 9 and 10
The connector supports Vignette V7.

About the Vignette V7 Connector

The Vignette V7 connector extracts content from a Vignette repository and submits to any JCR based application or any JCR adapter. An architectural overview is as follows:

The connector can be used for the following main purposes:

  1. Read users, groups, group memberships, and content (incl. ACLs) stored in the Vignette repository.
  2. Search content stored in the Vignette repository
  3. Repository Full scan: the whole content and all users, groups and group memberships can be extracted and processed by the application using the connector.
  4. Incremental updates: registered applications receive a notification on available content, user and permission updates. The notification frequency is configurable.

Reading from the Vignette Repository

The connector differentiates between Vignette projects, folders, records and files, and maps them to respective JCR node types in the Vignette namespace. The connector accesses the Vignette repository through the Vignette CMS API.

JCR Mapping Rules or Node Type Mapping?

The connector maps any Vignette ObjectType, including custom types, to the JCR API according to the following rules:

  • The NodeType name is the Vignette ObjectType name qualified by a default namespace. Example: “Article” maps to vgn:article.
  • The JCR properties are Vignette’s attribute definitions qualified by a default namespace. Example: “title” maps to vgn:title.
  • Any autogenerated attributes are mapped as JCR autocreated and are mandatory.
  • If the ObjectType has any relations, they are mapped as children of the JCR nodes including the name and type of relation.
The JCR connector exposes Vignette’s content according to the project-hierarchy starting with the root level with all RootProjects.

JCR add-ons

In addition to the mapping rules, a JCR connector includes the following add-ons:

  • All mapped NodeTypes are based on the NodeType vgn:record, which defines the jcr:creationDate and jcr:modificationDate properties. These properties are mapped to Vignette’s creationTime and lastModTime meta-data attributes respectively. The vgn:record NodeType extends JCR nt:hierarchyItem and can be used in nt:file/folder structures.
  • StaticFiles are converted into a NodeType that inherits the JCR nt:file. The actual binary file content is mapped to a child of the node, such as nt:file/jcr:content/jcr:data. The child NodeType vgn:ContentNode is based on nt:resources. The file’s binary content is accessible as a JCR value of jcr:data attribute. The filename and extension determines the JCR:mimeType attribute.
  • Each NodeType includes the following additional properties:
  • vgn:sites, a multivalued string property, contains a value for each site where the node is published. The value is the name of the site.
  • vgn:channels, a multivalued string property, contains a value for each channel to which a node belongs to. The value is the name of the channel.
  • vgn:status. If Vignette’s ManagedObject contains status information, a property called vgn:status is also added. vgn:status is a string value that reflects the approved status of the object.

Executing Queries on the Vignette Repository

The connector supports queries on the Vignette repository. For example, the following XPath query:
//element(*,vgn:PROJ)
        
returns all files in the Vignette repository.

Apply Vignette Access Control Lists (ACL)

All Vignette ACLs are read from the Vignette repository and converted into JCR permissions accessible through the JCR API.

Repository Full Scan

Depending on the data volumes, full scan time requirements and the available hardware infrastructure, the connector can run in one or more instances. The latter configuration enables full scan partitioning based on configurable views on the Vignette repository.

Incremental Updates (Content, Users, Permissions)

Content Updates

The connector periodically checks for content updates in the Vignette repository (modified, created or deleted files and folders). The frequency of these checks is configurable. The connector converts the received updates into JCR events, triggering an incremental content update in registered applications.

User and Permission Updates

The connector periodically checks for user and permission updates in the Vignette repository (users, groups and group memberships). The frequency of these checks is configurable. The connector converts the received updates into JCR events, triggering an incremental update in registered applications.
Users and permissions updates are sent to the registered application, when the configurable frequency triggers an update notification.

Installing the Vignette V7 Connector

Requirements

The connector requires the following:

  • Day Content Repository Extreme 1.2 (CRX 1.2) or later
  • Vignette API jar files (vgn-appsvcs-cda.jar and thirdparty-combined.jar)
  • Vignette V7 connector 1.2

Installing and Configuring CRX 1.2

Install CRX 1.2 following the instructions in the CRX Installation Guide.

Note

Note: <crx install> referenced in the documentation is the home of the CRX Installation. The home can be selected during the CRX Installation.

Unpacking the CRX Web Archive

To install the connector, you need to unpack the CRX Web archive, so you can access its contents individually. Proceed as follows:

  1. Go to the /server/webapps directory
  2. Rename the archive file crx.war to crx_ori.war
  3. Create a new folder named crx.war
  4. Extract the archive crx_ori.war to the folder crx.war

CRX Event Listener

If you plan to use the CRX Event Listener, you will also need the crx-1.2-extension.

Installing the Vignette V7 Connector

Installing the Remote Access Extension

To allow the connector to remotely access your Vignette V7 repository, a custom remote access extension needs to be deployed on the Vignette servlet container.

The remote access extension webapp crx2vignette.war does not contain the Vignette libraries it needs to access the Vignette V7 repository. You need to make the vgn-appsvcs-cda.jar and thirdparty-combined.jar files available to the webapp either via the shared classpath of the servlet container or by embedding the jar files into the WEB-INF/lib folder of the webapp. The latter is described in steps 1-3 of the following instructions.

  1. Unpack crx2vignette.war (this file is contained in crx2vignette-1.2.zip, see 3.3.2) to a temporary directory preserving the directory structure of the files contained in crx2vignette.war.
  2. Copy the following files to /WEB-INF/lib of the extracted file structure: vgn-appsvcs-cda.jar and thirdparty-combined.jar. Please take these files from your Vignette V7 installation.
  3. Package the modified file structure into a new crx2vignette.war file.
  4. Sign in to the Vignette Runtime Services Administration Console
  5. Select “Deployments / Web Application Modules” within the VgnCluster. The crx2vignette.war must be deployed on the VgnCluster and not on VgnAdminServer.
  6. Select “Deploy a new Web Application Module...”
  7. Upload and install the modified crx2vignette.war file.
If the Vignette administration console is bound to another address than localhost:27001, edit the console.host and console.port settings in the WEB-INF/web.xml file inside the crx2vignette.war archive to match the correct console address.

Installing the Connector

1. Extract the file crx2vignette-1.2.zip to a temporary directory. The distribution contains the following files and folders:

  • README.txt: This file contains the latest information on the Vignette V7 connector.
  • LICENSE.txt: The license files provide you with the terms and conditions of the use of this product. The same information is also available in the online documentation.
  • /lib:This folder contains the Vignette V7 connector library and the required remote access extension as well as other libraries that the adapter requires.
  • /docs: This folder contains this documentation.
  • /etc: This folder contains configuration files for the Vignette V7 connector.
2. Copy crx2vignette-1.2.jar to <crx-install>/server/webapps/crx.war/WEB-INF/lib.
3. Copy the "vignette.properties" file to the <crx-install>/server/etc directory of your CRX installation and set configuration parameters (see chapter 4.2).
4. Copy "etc/crx.vignette" to the <crx-install>/server/crx/workspaces directory of your CRX installation.

Note

Note:The workspace directory now contains a Vignette folder. When you start CRX, CRX creates the workspace based on the information in the workspace.xml file. The first time you log into the workspace, CRX creates the required workspace files.

5. Copy the "vignette_login.conf" (JAAS) file to the <crx-install>/server/etc directory of your CRX installation.
6. Configure the vignette_login.conf. See chapter 4.3.
7. Set "-Djava.security.auth.login.config=etc/vignette_login.conf" in your CRX Java startup batch file.
8. Restart CRX 1.2 and access the crx.vignette workspace to test access to the Vignette V7 system.

Configuring the Vignette V7 Connector

Configuring the Vignette V7 Connector

The Vignette V7 connector uses several configuration files, which you can find in the /etc directory of the Vignette V7 connector folder.

Vignette Connector Configuration

You can configure the Vignette connector in the file vignette.properties.

Workspace Configuration

The workspace is used by the connector as view on the Vignette repository. A crx.vignette workspace has to be created and configured.

JAAS Configuration

The file vignette_login.conf contains pre-configured login information to Vignette V7 and the configurable parameter defining the frequency of updates on users, groups, and group memberships changes (synchronization interval).

Vignette Connector Configuration

Configure the following entries in the vignette.properties file:

Set Username and Password

Default location: com.day.crx.vgnt.url=http://vcm.host.com:27110/crx2vignette/
Default username: com.day.crx.vgnt.username=vgnadmin
Default password: com.day.crx.vgnt.password=vgnadmin

Set JNDI Naming Factory

The JNDI naming factory is the provider that contains the CRX repository.
Default location: java.naming.provider.url=http://jcr.day.com
Default naming factory: java.naming.factory.initial=com.day.util.jndi.provider.MemoryInitialContextFactory

Set the JNDI Name for the CRX Repository

Default name: com.day.crx.repository=crx

Set the Vignette Workspace in the CRX Repository

Default name: com.day.crx.workspace=crx.vignette

Set the CRX Administrator Username and Password

Default username: com.day.crx.username=admin
Default password: com.day.crx.password=admin

Set the Workspace Username and Password

Default username: com.day.crx.workspace.user.name=admin
Default password: com.day.crx.workspace.user.pwd=admin

Set the Switch

This is used if a PersistenceManger starts an Event-Injection.
Default value: com.day.crx.vngt.persistance.dispatchevents=true

Set the LDAP Configuration

These values allow access to Vignette principals.
Default location: com.day.crx.vgnt.ldap.url=ldap://localhost
Default authentication: com.day.crx.vgnt.ldap.authentication=simple
Default principal: com.day.crx.vgnt.ldap.principal=cn=Admin
Default credentials: com.day.crx.vgnt.ldap.credentials=

Set the LDAP Names for Vignette Users and Groups

Default name for users: com.day.crx.vgnt.ldap.people=ou=people,ou=VgnLDAPRealm,dc=vgndomain
Default name for groups: com.day.crx.vgnt.ldap.groups=ou=groups,ou=VgnLDAPRealm,dc=vgndomain

Configuring the Java Authentication and Authorization Service (JAAS)

In the pre-configured vignette_login.conf file set the synchronization interval parameter defining how often the connector gets updates on user, group, and group memberships from the Vignette V7 repository.

  • sync_interval (in seconds, default is 3’600 seconds)

Troubleshooting

If you cannot login to the crx.vignette workspace, and there is a log message "Authentication error: <the Vignette username configured in vignette.properties>".

  1. Verify that the username and password configured in vignette.properties are correct and that you can use them to login normally to the Vignette Administration Console.
  2. Check that the administration console host and port settings in WEB-INF/web.xml inside the deployed crx2vignette.war are correct.

Copyright, Licenses, Disclaimers

This section lists all licenses, copyright notices and disclaimers which must be explicitly stated in connection with the CRX Connector for Vignette.

CRX Connector for Vignette

The CRX Connector for Vignette is covered by the following license. This includes the following libraries included with the product: - crx2vignette-1.2.jar - crx2vignette.war
CRX Content Repository Extreme (r) Connector for Vignette ("the Software"). 
By installing the Software you agree to the following terms and conditions.

This Software is protected by copyright law and international treaties. This
Software is licensed (not sold), and its use is subject to a separate license
agreement between you and Day or Day's authorized resellers. By installing the
Software you confirm to be an authorized user of the software in accordance
with such license agreement. The unauthorized use, copying or distribution of
this Software may result in severe criminal or civil penalties, and will be
prosecuted to the maximum extent allowed by law.

Remote Verification. You acknowledge and agree that the Software may contain
verification and reporting functionality that allows the remote reporting of
your usage of the Software for the purpose of verifying your compliance with
these terms and conditions. If remote verification reveals that you are using
the Software in violation of these terms and conditions, you agree to cease
such unauthorized use and to pay Day's reasonable expenses and a penalty fee
associated with such remote verification and your unauthorized use.

DAY, the DAY logo, Communique, ContentBus and CRX Content Repository Extreme
are registered trademarks and service marks, or are trademarks and service
marks, of Day Management AG, Switzerland, in various countries around the world.

All other product names and company logos mentioned in the information,
documents or other items provided or available herein may be the trademarks of
their respective owners.