Document Exchange Gear

Module name: docexch

The Document Exchange Gear lets visitors interact with any document repository. Depending upon their security permissions, visitors can upload, download, annotate, edit, and share documents with other registered users in the portal community. Portal Administrators can use security permissions to maintain the integrity of the document repository. ATG Portal can also use the documents in the repository to create new dynamic content within the PAF. Portal users can perform keyword searches on the repository using the Repository Search Gear.

Configuring a Document Repository

To specify the location of the document repository, you must be a Portal Administrator.

A repository used by the Document Exchange Gear needs to have one item descriptor that corresponds to a document. The document item descriptor needs to define properties that store the following information:

file name
file data
MIME type
file size
description
title
author
create date
status
gear ID
discussion ID

If you configure the gear to point to your own repository, you should set the maxlength attribute of the document title and description properties in the repository so that users creating documents are informed if they attempt to create documents with titles or descriptions that overflow the size of the database column. These properties are already set in the default document repository. You must do this only if you configure the gear to use another repository. To set the maxlength attribute, edit the repository definition XML file and add the maxlength attribute as in this example:

<property name="title" column-name="title" data-type="string">
  <attribute name="maxLength" value="254"/>
</property>
<property name="description" column-name="description" data-type="string">
  <attribute name="maxLength" value="400"/>
</property>

When you configure the document exchange gear to use a repository other than the default repository and RQL query, you must tune your database and repository to achieve the best possible performance. For more information on performance tuning, refer to the Platform Installation and Configuration Guide.

Configuring the Expression Editor

Note that the expression editor in the ACC is configured to point to the default document repository, /atg/portal/gear/docexch/SplitDocumentRepository in the /atg/portal/gear/docexch/docexch-expression-grammar.xml file found in <ATG11dir>/Portal/docexch/lib/docexch.jar:

...
<token>
   <expression-class>atg.ui.expreditor.targeting.RepositoryItemSetExpression
   </expression-class>
   <assistant-class>atg.ui.expreditor.targeting.RepositoryItemSetAssistant
   </assistant-class>
   <attribute
        name="repositoryName"
        value="/atg/portal/gear/docexch/SplitDocumentRepository"/>
   <attribute name="repositoryItemType" value="document"/>
   <required/>
   <description>Choose document...</description>
</token>
...

If you use a different document repository, you need to modify this token tag in the docexch-expression-grammar.xml expression editor grammar file to point to the appropriate document repository and document repository item type. See the Personalization Programming Guide for more information about how to modify expression editor grammar files.

Installation Configuration

To configure the Document Exchange Gear in the Portal Administration:

  1. Click the configure link for the gear in the Available Gears page. A page opens titled Configure Gear Definition: Document Exchange.

  2. Enter the Nucleus address of the repository that will store the gear’s documents and click Continue.

  3. In the Repository Item Type field, select the item type that corresponds to documents in the repository and click Continue.

  4. Map the properties of the selected item type to the properties needed by the gear. Select the property from the document item descriptor that is used for each of the following:

    file name
    file data
    mime type
    file size
    description
    title
    author
    create date
    status
    gear id
    discussion id

    Click Finish.

  5. Click the Repository Limitations link.

  6. Select whether the gear exposes the repository as read-only or read/write. If the gear uses a read-only repository, portal users will not be able to add documents. You can configure an instance of the gear to adjust the permissions of a read/write gear to limit who can add or modify documents.

  7. Set a maximum file size for documents in the repository and click Finish.

Instance Configuration

To create an instance of the Document Exchange Gear in a community:

  1. Enter the Community Administration and click the Select New Gears link in the side navigation panel.

  2. Enter a gear name and description.

  3. Select sharing and Make visible to options.

  4. Click Done.

To configure an instance of the Document Exchange Gear:

  1. Enter the Community Administration and click the configure link for the gear instance.

  2. Click the additional configurations link.

  3. Apply the appropriate settings in the appearance page. Click Save.

  4. Click the permission link. You can select which groups of portal users are permitted to:

  5. Read and discuss documents

  6. Add new documents

  7. Change the status field for documents

    Click Save.

  8. Click the functionality link. You can select the features rendered in the Document Exchange Gear instance.

    Select Enable Discussion to include the discussion board feature in the gear instance.

    Select Enable Search to include a search field in the gear instance. Note that this search field enables searches only within the documents of this gear instance. For a broader search function, use the Repository Search Gear.

    Select Attachment Required to require that each new item have a file attachment.

    Click Save.

  9. Click the alerts link. You can configure whether alerts are sent to users when documents are added, modified, or deleted in the gear instance.

Virus Protection for the Document Exchange Gear

The Document Exchange Gear allows users to upload files into the portal. There is a risk that some of these files might contain viruses. The gear does not check for viruses or other unacceptable content. However, it includes a stub method that a gear developer could override to implement document checking.

The stub method is found in the atg.portal.gear.docexch.DocumentFormHandler class. You can find the source code for this class at:

<ATG11dir>/Portal/docexch/src/classes.jar/atg/portal/gear/docexch/
DocumentFormHandler.java

The stub method is:

public void validateFileContents(UploadedFile pUploadedFile) { // no op }

You can extend the DocumentFormHandler and override this method to reject an uploaded document based on any criteria. For example, you might implement virus scanning, looking for offensive words, or whatever checks your application requires. In addition to overriding the validateFileContents method, you should also add an exception to the file upload form, as in this example:

addFormException( new DropletException(getAbsoluteName() + ".value."
   + "uploadedFile", "FILE_CONTENT_REJECTED")); */
Announcements Gear

Module name: docexch

The Announcements Gear is just a different version of the Document Exchange Gear. You can install the Announcements Gear, using the Gears > New Gear page in the Portal Administration interface. Browse to the gear’s manifest at <ATG11dir>/Portal/docexch/announcements-manifest.xml and upload the manifest.

The Announcements Gear is configured just like the Document Exchange Gear. See the Installation Configuration and Instance Configuration sections of Document Exchange Gear.

Copyright © 1997, 2015 Oracle and/or its affiliates. All rights reserved. Legal Notices