Annoted plug-in descriptor file

The RSuite® plug-in descriptor file, rsuite-plugin.xml, declares all the parts of an RSuite plug-in, using extension provider elements (<extensionProvider id="type">). No particular type of extension provider is required, and elements of the different types can be specified without regard to order. Extension provider types are:
  • rsuite.ContextMenu
  • rsuite.EventBus
  • rsuite.Forms
  • rsuite.HotFolder
  • rsuite.ManagedObjectAdvisor
  • rsuite.ManagedObjectValidation
  • rsuite.Reporting
  • rsuite.Scheduler
  • rsuite.Search
  • rsuite.TransformationProvider
  • rsuite.UI
  • rsuite.WebService
  • rsuite.Workflow
The extension provider elements are described in the examples below.

You can download an annotated descriptor file, rsuite-plugin-annot.xml. Since it includes examples of all the different types of extension provider elements, it is not a functioning plug-in descriptor. Use it as a reference for the markup.

RSuite v4 rsuite-plugin-annot.xml

This example, rsuite-plugin-annot.xml, includes all the different types of extension provider and other XML elements that can be used in a 4.0 plug-in descriptor. The annotations explain the elements.

rsuite-plugin

<rsuite-plugin id="my-plugin-name"
               version="1.0">
rsuite-plugin@name and rsuite-plugin@version: Appear in the plug-in listing on the admin console.

lifecycleListener

<lifecycleListener
      type="com.rsi.rsuite.lifecycle.MyPluginLifecycleListener"/>
lifecycleListener: Declaration for a plug-in lifecycle listener. The Java class declared in the type attribute implements com.reallysi.rsuite.api.extensions.PluginLifecycleListener.

rsuite.WebService

<extensionProvider id="rsuite.WebService">
    <staticWebService path="/WebContent"
                   root="/my-plugin-name"

staticWebService: Maps a directory (in this case "WebContent") in the plug-in to be a public folder addressable by URL, which means paths in the plug-in can be accessed as /rsuite-cms/plugin/my-plugin-name/path.

 <remoteApiDefinition id="myService" handler="com.rsi.rsuite.webservices.MyWebService"/> 

remoteApiDefinition: Declaration of a Java class. Other configuration items in rsuite-plugin.xml can reference the id. The ID is used to provide a REST URL for the service as well, in the pattern /rsuite/rest/v1/api/id. The code is run when invoked through a user or system action, often declared through association with a context menu action in rsuite-plugin.xml.

remoteApiDefinition/@handler: Must implement the RSuite RemoteApiHandler interface.

</extensionProvider>

rsuite.Workflow

<extensionProvider id="rsuite.Workflow">
      <workflowExecutionAdvisor id="lnp:workflowExecutionAdvisor"
        handler="com.rsi.rsuite.workflow.MyWorkflowExecutionAdvisor"
        description="Sort incoming workflow jobs to the appropriate workflow pool"
  • workflowExecutionAdvisor: Declaration for a Java class that balances workflow process instances across pools.
  • workflowExecutionAdvisor/@handler: The Java class being declared. Must extend com.reallysi.rsuite.api.workflow.DefaultWorkflowExecutionAdvisor.
  • workflowExecutionAdvisor/@description: A description for documentation.
 </workflowExecutionAdvisor>
<actionHandler 
  label="My Custom Action Handler"
  type="com.rsi.rsuite.workflow.MyActionHandler" 
  description="Process content at a specific point in a workflow process">
  • actionHandler: Declaration for a Java class that defines automated actions to take at a given point in a workflow. If not declared, the action handler a workflow process definitioncannot refer to it, and it does not appear in the drop-down of action handlers in the RSuite admin UI.
  • actionHandler/@type: The Java class being declared. Must extend com.reallysi.rsuite.api.workflow.AbstractBaseNonLeavingActionHandler.
  • actionHandler/@description: A description for documentation.
<variableList>      
        <variable>
         <name>aCustomVariable</name> 
        </variable>
  • variableList: A list of action handler variables. Optional.
  • variable: A variable that is passed into the action handler at run time. It is set in the workflow process definition.
   </variableList> 
</actionHandler>
<taskUIConfiguration scope="user,roles">
  • taskUIConfiguration: Section for configuring the panels on the Tasks tab
  • taskUIConfiguration/@scope: Panels to which this configuration applies. Choices are user, roles, and manager. It is typical to use one taskUIConfiguration element for the first two and another for the last.
<inboxRowsPerPage>20</inboxRowsPerPage>
  • inboxRowsPerPage: Number of tasks per page to display in panels using this configuration. Can also be set with taskUIConfiguration/@rowsPerPage.
   <inboxColumnList>
    <column name="name" label="Task"/> 
    <column name="description" label="Description"/> 
    <column name="projectName" label="Project"/> 
    <column name="workflowStatus" label="Workflow Status"/>
   </inboxColumnList> 

inboxColumnList: Columns to include in panels using this configuration. Can refer to built-in names as well as custom names, all of which are workflow variable names.

   <inboxFilterList>            
      <filter name="name" label="Task Type"/> 
      <filter name="projectName"  label="Project"/> 
   </inboxFilterList>

inboxFilterList: Filters available for panels using this configuration. Can refer to any workflow variable name.

</taskUIConfiguration>
</extensionProvider>

rsuite.HotFolder

<extensionProvider id="rsuite.HotFolder">
      <hotFolderAdvisor type="com.rsi.rsuite.advisors.workflow.MyHotFolderAdvisor" 
        description="This advisor ignores files that aren't zip files."/>
  • hotFolderAdvisor: Declaration for a Java class that is run when a file is uploaded through a hot folder and prior to the subsequent action (typically a workflow process). Declaring the advisor puts it into effect.
  • hotFolderAdvisor/@type: The Java class being declared.
  • hotFolderAdvisor/@description: A description for documentation.
</extensionProvider>

rsuite.Scheduler

<extensionProvider id="rsuite.Scheduler">
    <scheduledJobHandler 
       description="Scheduled job to do something repeatedly"
       handler="com.rsi.rsuite.job.MyScheduledJob" 
       id="myScheduledJob"/>
  • scheduledJobHandler: Declaration for a Java class that runs when invoked by a configured scheduler (schedule is configured via Java code, Groovy scripting, or admin UI).
  • scheduledJobHandler/@handler: Must implement com.reallysi.rsuite.api.scheduler.ScheduledJobHandler.
</extensionProvider>

rsuite.EventBus

<extensionProvider id="rsuite.EventBus">
    <eventHandler type="com.rsi.rsuite.eventhandlers.MyEventHandler"   
      includeRegex="task.*|workflow.process.completed"/>
  • eventHandler: Declaration for a Java class that is invoked when the associated event(s) occur(s). Declaring the class puts it into effect.
  • eventHandler/@type: Must implement com.reallysi.rsuite.api.event.EventHandler.
  • eventHandler/@includeRegex: The regular expression for the event or events to be matched. The built-in events are listed in an appendix of the RSuite Extension Guide. Custom events can be published by custom Java classes.
</extensionProvider>

rsuite.ManagedObjectAdvisor

<extensionProvider id="rsuite.ManagedObjectAdvisor">
   <managedObjectAdvisor type="com.rsi.rsuite.advisors.mo.MyMoAdvisor"/>
  • managedObjectAdvisor: Declaration for a Java class that applies custom processing or captures important information during update and load operations. Declaring the advisor puts it into effect.
  • managedObjectAdvisor/@type: Must implement com.reallysi.rsuite.api.control.ManagedObjectAdvisor.
</extensionProvider>

rsuite.ManagedObjectValidation

<extensionProvider id="rsuite.ManagedObjectValidation">
   <managedObjectValidator type="com.rsi.rsuite.validation.MyValidator"/>
  • managedObjectValidator: Declaration for a Java class that applies custom validation rules upon the specified event (e.g., before check-in). Declaring the validator puts it into effect.
  • managedObjectValidator/@type: Must implement com.reallysi.rsuite.api.validation.ManagedObjectValidator.
</extensionProvider>

rsuite.UI

<extensionProvider id="rsuite.UI">
    <scriptInclude src="/my-plugin-name/js/myCustomJavascript.js"/>

scriptInclude: Reference to a custom Javascript file included in the plug-in. All custom Javascript must be declared in this way.

 <styleInclude
       src="/my-plugin-name/css/styles.css"/>

styleInclude: Reference to a custom LESS (CSS) file included in the plug-in. All custom stylesheets must be declared in this way.

 <messageTable
       src="/my-plugin-name/static/messages.xml"/>

messageTable: Reference to an XML file in the same plug-in that contains text to use in UI labels. Values in the message file are referred to elsewhere in the same plug-in. See sample <messages> instance below for more information.

<contentDisplayAdvisor id="myContentDisplayAdvisor" 
    type="com.rsi.rsuite.advisors.content.MyContentDisplayAdvisor" 
    label="My Content Display Advisor"
    description="A CDA that adjusts the appearance of objects in the UI."/>
  • contentDisplayAdvisor: Declaration of a content advisor, which can adjust the appearance of objects as listed in the UI and of the contents and order of object lists.
  • contentDisplayAdvisor/@type: Extends com.reallysi.rsuite.api.content.DefaultContentDisplayAdvisor.
Note: These elements for the rsuite.UI type are deprecated—<pageConfiguration> and <searchUIConfiguration>.
</extensionProvider>

rsuite.TransformationProvider

<extensionProvider id="rsuite.TransformationProvider">
  <namedPreviewTransformer mimeType="text/html"   
     previewXsltUri="rsuite:/res/plugin/my-plugin-name/xslt/myPreview.xsl" 
     suggestedFileName="preview.htm" 
     transformName="myHtmlPreviewHTML"/>

namedPreviewTransformer: Declaration of an XSLT script that transforms an XML MO or container XML. The name is referenced by a menu action elsewhere in the plug-in. If the result is not HTML or if the browser should not treat it as HTML, the mimetype can be adjusted appropriately.

  <transformationProvider name="myPreviewProvider"
     type="com.rsi.rsuite.transformation.MyPreviewProvider"
     mimeType="application/octet-stream"/>
  • transformationProvider: Declaration of a Java class that transforms the supplied content when an XSLT is insufficient. The name is referenced by a menu action elsewhere in the plug-in. If the result is not HTML or if the browser should not treat it as HTML, the mimetype can be adjusted appropriately.
  • transformationProvider/@type: Must implement com.reallysi.rsuite.api.transformation.TransformationProvider.
</extensionProvider>

rsuite.ContextMenu

<extensionProvider id="rsuite.ContextMenu"> 
            <contextMenuRuleSet name="myMenuSet" scope="allNodes">
  • contextMenuRuleSet: A combination of a menuItemList (list of menu items) and a ruleList (list of rules defining objects for which the menu items should appear). Include as many contextMenuRuleSet elements as needed.
  • contextMenuRuleSet/@scope: The scopes (menu types) in which the menu items should appear. The list of scopes is allNodes, browseTree, browseTreeNode, clipboard, clipboardNode, searchResults, searchResultsNode, system, target, targetNode, targetTask, tasks, taskDetails, taskDetailsNode, user.
 <menuItemList> 
   <menuItem id="myMenuItem">
  • menuItem: An action to appear on an RSuite action menu.
  • menuItem/@id: The ID used to refer to the menu item from rsuite-config.xml to control order. Deprecated element: <type>
<actionName>rsuite:invokeWebservice</actionName>

actionName: The type of action to invoke. See the Extension Guide for an explanation of which properties are applicable to each actionName. Custom actions can be defined through Javascript. Often, an actionName requires an associated property to identify which extension ID to use for the action. In the case of rsuite:invokeWebservice, remoteApiName is required. Other commonly used action names and required property values are:

  • rsuite:startWorkflow & property/@name=processDefinitionName
  • rsuite:preview & property/@name=transform
  • rsuite:editMetaData (no property required)
<property name="remoteApiName" 
          value="myService"/>

property/@name=remoteApiName: The ID assigned to the Java class declaration for an action of type rsuite:invokeWebservice.

<label>My action</label>

label: The menu item label

<property name="rsuite:icon"
          value="/rsuite-cms/plugin/my-plugin-name/images/myicon.png"/>

property/@name=rsuite:icon: The icon to use in the menu. Optional.

 <property name="rsuite:group"
           value="mygroup"/>

property/@name=rsuite:group: The name of the group of menu actions with which the current action should be grouped. Optional.

 <property name="rsuite:path" 
           value="My Main Menu/My Submenu"/>

property/@name=rsuite:path: The menu path under which the menu action should be made available. Multiple levels can be defined. Optional.

 <property name="serviceParams.myCustomParam" 
           value="A value"/>

property/@name=name: A means for passing custom parameters to the service or other extension class invoked.

 <property name="formId"
           value="myCustomForm"/>

property/@name=formId: The form that should be shown prior to invoking the specified action. Optional.

 <property name="formParams.myCustomFormParam" value="A
           value"/>

property/@name=formParams.name: A means for passing custom parameters to the form invoked prior to invoking the specified action.

 <property name="showProgressMeter"
                value="true"/>

property/@name=showProgressMeter: Shows progress meter for long-running processes.

 <property name="timeout"
           value="0"/>

property/@name=timeout: Duration after which a web service should time out (override of default). "0" means the process should not time out. Optional.

<property name="useTransport"
          value="iframe"/>

property/@name=useTransport: Returns results (if any) using specified method rather than in the default dialog box. Choices are iframe, window, and tab. Optional.

 <property name="minimumDelay"
           value="60"/>

property/@name=minimumDelay: Specify a delay between the return of this action from the returning Web service and invocation of the Web service. Optional.

</menuItem>
</menuItemList>
<ruleList>

ruleList: A list of inclusion and exclusion rules that define the characteristics of objects for which the menu items should appear.

<rule>include nodeType ca,canode,mo,mononxml</rule>

<rule>include rule: An inclusion rule.

<rule>exclude role Author,Contributor</rule>

<rule>exclude rule: An exclusion rule.

Additional include examples (all are also valid exclude rules):

          <rule>include nodeType folder</rule>    
          <rule>include caType dita-topic,dita-ul</rule>    
          <rule>include elementType topic</rule>
          <rule>include elementType {http://www.w3.org/1999/02/22-rdf-syntax-ns#}:RDF</rule>    
          <rule>include lmdValue isPrimary</rule>    
          <rule>exclude lmdValue Publication_Cycle_Status=outWithVendor</rule>    
          <rule>include lmdValue imageType=CP,B&W</rule>    
          <rule>include hasPermission edit</rule>
</ruleList> 
</contextMenuRuleSet>
</extensionProvider>

rsuite.Forms

<extensionProvider id="rsuite.Forms">
  <formDefinition description="A form used to do something in RSuite" 
  id="myCustomForm" 
  label="My Custom Form" 
  handler="com.rsi.rsuite.formhandler.MyFormHandler">
  • formDefinition: A form that can be configured to appear when a menu action is selected or that can be invoked from code.
  • formDefinition/@id: The form ID used for referring to the form in code or configuration statements.
  • formDefinition/@label: The label presented in the form title bar.
  • formDefinition/@handler: The Java class called prior to presenting a form (to populate the form, construct the form, etc.). Must implement com.reallysi.rsuite.api.search.SearchFormHandler.
  • formDefinition/@description: A description for documentation purposes.
<instructions>Fill out the form, then click on OK. </instructions>

instructions: Instructions that appear at the top of the form dialog. Can also be provided using formDefinition/@instructions.

<property name="dialogOptions.width" value="950pt"/>

property/@dialogOptions.width: Set fixed width of form. Optional.

<property name="rsuite:icon" value="checkin"/>

property/@rsuite:icon: Icon to display in the form title bar. A reference to a built-in icon. Custom icons can be referred to by URI. Optional.

<column name="myColumn1"> 

column: A list of parameters (i.e., fields) to be included as a column on the form.

column/@name: The column name, which can be referred to as a CSS class or in code.

<param>

param: A form parameter (field).

<name>param1</name> 

name: The form parameter name. Appears as a class value in the HTML so it can be used for styling. Each parameter and its the corresponding values are provided as an argument to the Java class called after the form is closed. Can also be provided as param/@name.

<label>A form field </label> 

label: The form parameter label. Can also be provided as param/@label.

<formControlType>select</formControlType> 
formControlType: The type of control used for the form parameter. Defaults to input (aka text). Can also be provided as param/@formControlType. Built-in types are:
  • autocomplete
  • checkbox
  • date | datepicker
  • daterange
  • file
  • hidden
  • input | text
  • label
  • multiselect
  • radiobutton
  • select
  • submitbutton
  • textarea
Custom types can also be created. Additional types available through plug-ins from RSuite include, for example, "taxonomy".
<metaDataType>contextual</metaDataType>

metaDataType: Set to "contextual" to search contextual values rather than MO values. Can also be provided as param/@metaDataType.

<allowMultiple>true</allowMultiple> 

allowMultiple: Determines whether the user can select more than one value. Defaults to FALSE. Can also be provided as param/@allowMultiple.

<readOnly>true</readOnly>

readOnly: Determines whether the user can modify the values. Defaults to FALSE. Can also be provided as param/@readOnly.

<required>true</required>

required: Determines whether the user is required to enter a value before the form can be submitted. Defaults to FALSE. Can also be provided as param/@required.

<validation errorMessage="That's not right!" 
            regex="\a\d"
            required="false"/>
  • validation: Validation rules for the field data forms. Optional. Can also be provided as param/@required.
  • validation/@regex: The regular expression that will be applied to determine whether the field value is valid.
  • validation/@errorMessage: The message presented to the user if the value is invalid.
  • validation/@required: Determines whether the user is required to enter a value before the form can be submitted.
<optionList>

optionList: A list of values that will populate the control when presented. These values will precede any provided via a datatype.

<option label="Cool" value="cool"/> 
            <option label="Really Cool" value="reallycool"/> 
            </optionList> <datatype name="myDatatypeName"/> 

datatype: A reference to a datatype defined in this rsuite-plugin.xml. An alternative way to populate the list of values.

<sortOptions>asc</sortOptions> 

sortOptions: Sorting type to be used when multiple values are presented. Possible values are asc, desc, natural, and noSort. Can also be provided as param/@sortOptions.

<required>style</required> 

style: CSS style markup for the parameter. Can also be provided as param/@style.

<required>styleClass</required>

styleClass: CSS class name. Can also be provided as param/@styleClass. Deprecated elements: <size>

</param>
</column> 

Deprecated elements: <paramList> rather than <column>. <paramList> contained <param>s with child <col>s to set the column.

</formDefinition>
<datatypeDefinition name="myDatatypeName" formControlType="select"> 

datatypeDefinition: A list of values that can be referred to by forms or code.

<description>A datatype for you</description>

description: A description for documentation purposes. Optional. Can also be provided as datatypeDefinition/@description.

<optionList> 
       <option label="Lame" value="lame"/> 
       <option label="Really Lame" value="reallylame"/> 
       </optionList> 
       </datatypeDefinition>
       
       <datatypeDefinition name="myOtherDatatypeName" 
       formControlType="select" 
       description="My favorite datatype">
 <optionListProvider handler="com.rsi.rsuite.datatypes.MyCustomDatatype"/> 
  • optionListProvider: A Java class that populates List<DataTypeOptionValue> upon request.
  • optionListProvider/@handler: Must implement com.reallysi.rsuite.api.forms.DataTypeOptionValuesProviderHandler.
</datatypeDefinition> 
</extensionProvider>

rsuite.Reporting

<extensionProvider id="rsuite.Reporting">
        <reportDefinition description="Report on everything that happened." 
        handler="com.rsi.rsuite.report.MyCustomReport" 
        id="myReport" 
        label="The Everything Report">
  • reportDefinition: The definition for a report that appears on the RSuite "Reports" tab.
  • reportDefinition/@handler: The Java class invoked when the user submits the report request. Must implement com.reallysi.rsuite.api.report.ReportGenerator.
  • reportDefinition/@label: The report name listed on the Reports tab.
  • reportDefinition/@description: A description of the report that appears below the report name on the Reports tab.
<instructions>Fill out the form then push Submit.</instructions>

instructions: Instructions that appear at the top of the report form. Can also be provided using reportDefinition/@instructions.

<property name="rsuite:icon" value="/rsuite-cms/plugin/my-plugin-name/images/myreporticon.png"/>

property/@name=rsuite:icon: The icon that appears next to the report name on the Reports tab. Optional.

<column name="myColumn1">

column: A column of one or more parameters (fields) for the report form. See example for <extensionProvider id="rsuite.Forms"><formDefinition>.

</column>
</reportDefinition>
</extensionProvider>