eXo Knowledge Reference Guide

The roles plugin component is used to define user roles in eXo Forum and eXo FAQ. Roles are a convenient instrument to define access to a set of functions within the application.

Currently, it only allows to define who is in the administrator role. Administrators get access to administration functions.

At runtime, the application get data from the roles plugin in order to decide whether the logged user has the administration role or not.

The plugin is configured in ks-plugins-configuration.xml file.

When a user signs in, his or her username, group and membership is compared with the user roles defined in the xml file that is provided by the roles plugin component.

In details:

At runtime of the Forum Service, the roles plugin component is called. The role plugin is configured in the ks-plugins-configuration.xml file. The component-plugin named add.role.rules.plugin refers to org.exoplatform.forum.service.conf.RoleRulesPlugin to create users for eXo Forum corresponding to the users that exist in the Organization database. Besides, the list of users who have administration roles is also defined.

  <component-plugin>
      <name>add.role.rules.plugin</name>
      <set-method>addRolePlugin</set-method>
      <type>org.exoplatform.forum.service.conf.RoleRulesPlugin</type>
      <description>add role rules</description>
      <init-params>
	      <value-param>
	        <name>role</name>
	        <description>name of the role</description>
	        <value>ADMIN</value>
	      </value-param>
	      <values-param>
	        <name>rules</name>
	        <description>rules of the role</description>
	        <value>root</value>
                <value>john</value> 
                <value>/platform/administrators</value> 
	        <value>member:/VIP</value>
		<value>validator:/VIP</value>
	        <!-value>*:/somegroup/somesubgroup</value->
	        <!-value>manager:/somegroup/someothergroup</value->
	      </values-param>
	 </init-params>
    </component-plugin>

When ks-plugins-configuration.xml file is executed, the administration role (with ADMIN value) will be checked and assigned to a matrix of users/groups/memberships defined inside "value" tags like below:

<value>...</value>

For example:

...
                <value>root</value>
                <value>john</value> 
                <value>/platform/administrators</value> 
	        <value>member:/VIP</value>
		<value>validator:/VIP</value>
...

With the example above, the default Forum Administrator are root , john, users in /platform/administrators group and users who are member/validator memberships in the VIP group.

When root, john or any user who belongs to the /platform/administrators group or users who have amember/validator memberships in the VIP group signs in to eXo Forum, he or she will be identified as the default Forum Administrator.

To add or remove the default Forum Administrator, simply edit ks-plugins-configuration.xml file and add or remove the correspondent "value" tags.

...             
                <values-param>
                 ...
                <value>...</value>
                 ...
                </values-param>
...

The default Forum Administrators can only change their roles by editing in ks-plugins-configuration.xml file.

At runtime, the modifications in the ks-plugins-configuration.xml file will be read and the database updated, the forum normal users and the default administration will be created correspondingly.

In KS, MailService comes from kernel, KS relies on this service to sends notifications via email.

This configuration initializes parameters for MailService, the parameters declare properties of a mail box that is used to send email notification.

At runtime of KS, when the send mail function is executed, org.exoplatform.services.mail.MailService will be called that refers to org.exoplatform.services.mail.impl.MailServiceImpl.

Properties of MailService are defined with the format:

...
 <component>
  <key>org.exoplatform.services.mail.MailService</key> 
  <type>org.exoplatform.services.mail.impl.MailServiceImpl</type> 
- <init-params>
- <properties-param>
  <name>config</name> 
  <property name="mail.smtp.auth.username" value="notifuser" /> 
  <property name="mail.smtp.auth.password" value="somepassword" /> 
  <property name="mail.smtp.host" value="smtp.example.org" /> 
  <property name="mail.smtp.port" value="465" /> 
  <property name="mail.smtp.starttls.enable" value="true" /> 
  <property name="mail.smtp.auth" value="true" /> 
  <property name="mail.smtp.debug" value="false" /> 
  <property name="mail.smtp.socketFactory.port" value="465" /> 
  <property name="mail.smtp.socketFactory.class" value="javax.net.ssl.SSLSocketFactory" /> 
  <property name="mail.smtp.socketFactory.fallback" value="false" /> 
  </properties-param>
  </init-params>
  </component>

...

Properties:

When sending an email in KS, those properties will use to connect to mail box(example: exoservice on gmail ) and send notification from there.

By fault, the default properties can only be changed by editing its value in ks-plugins-configuration.xml file and the user can configure an different mail box when deploying KS. Note that the properties which are used for SMTP Service must be exact.

At runtime, the modifications in ks-plugins-configuration.xml file will be read and updated, MailService will be executed depending on its properties.

Forum and FAQ applications allow to show some information about the posters. The way we retrieve that information is pluggable through contact provider implementations.

For public internet websites, you may want to allow user provide personal information such as personal email address and location. To enable this simply override the ContactProvider component in your configuration.

Configuration file format:

 <component>
    <key>org.exoplatform.forum.service.user.ContactProvider</key>
    <type>org.exoplatform.forum.service.user.PersonalProfileContactProvider</type>
 </component>  

For corporate websites, it is probably more advisable to use the business information such as professional phone or email address. In that case you would use the BusinessProfileContactProvider :

 <component>
    <key>org.exoplatform.forum.service.user.ContactProvider</key>
    <type>org.exoplatform.forum.service.user.BusinessProfileContactProvider</type>
 </component> 

If you run eXo Collaboration Suite on your portal you can get profile information from eXo Address Book contacts, including avatar image. To enable this nice feature :

 <component>
    <key>org.exoplatform.forum.service.user.ContactProvider</key>
    <type>org.exoplatform.forum.provider.cs.CSContactProvider</type>
</component>  

And finally you can create your own implementation to apply custom privacy policies.

The Initialization plugin component is used to define the default forum data in xml file. It includes categories,forums,topics and posts.

When Forum Service runs, it will get values which are returned from Initialization plugin component to initialize the default forum data.

Auto prune component is used to activate automatically the topics in specific Forums which are not activated (not viewed, edited or added post) for a period of time.

When Job Schedule Service runs, it will get values which are returned from Auto prune plugin component to identify the topics which have to be inactivated in Forum application. These topics will be invisible to users.

The properties of Auto prune plugin is configured in ks-plugins-configuration.xml file.

In details:

At the runtime of Job Schedule Service, Auto prune plugin component is called, then ks-plugins-configuration.xml file is executed, the component-plugin named ForumDeactiveJob will be referred to org.exoplatform.forum.service.conf.DeactivePeriodJob to inactivate the topics in specific Forum which satisfy predefined inactivation properties.

<component-plugin>
      <name>ForumDeactiveJob</name>
      <set-method>addPeriodJob</set-method>
      <type>org.exoplatform.forum.service.conf.DeactivePeriodJob</type>
      <description>add a Deactive job to the JobSchedulerService</description>
      <init-params>
        <properties-param>
          <name>job.info</name>
          <description>save the monitor data  periodically</description>
          <property name="jobName" value="DeactiveJob"/>
          <property name="groupName" value="KnowlegedSuite"/>
          <property name="job" value="org.exoplatform.forum.service.conf.DeactiveJob"/>
          <property name="repeatCount" value="0"/>
          <property name="period" value="7200000"/> <!- 2 hours->    
          <property name="startTime" value="+0"/>
          <property name="endTime" value=""/>               
        </properties-param>
        <properties-param>
          <name>deactive.info</name>
          <description></description>
          <property name="inactiveDays" value="1"/>          
          <property name="forumName" value="Live demo"/>          
        </properties-param>
      </init-params>
    </component-plugin>

The properties for Auto-prune plugin are defined in property tag with format like below:

...
          <property name="jobName" value="DeactiveJob"/>
          <property name="groupName" value="KnowlegedSuite"/>
          <property name="job" value="org.exoplatform.forum.service.conf.DeactiveJob"/>
          <property name="repeatCount" value="0"/>
          <property name="period" value="7200000"/> <!-- 2 hours-->    
          <property name="startTime" value="+0"/>
          <property name="endTime" value=""/>               
...
          <property name="inactiveDays" value="1"/>          
          <property name="forumName" value="Live demo"/>          
 ...

In details:

With start and end time, you can give a specific date in format:yyyy-mm-dd HH:mm:ss.sss to define the start and end time for DecactiveJob . Besides, deactive information is also defined:

By fault, the default properties can only be changed by editing its value in ks-plugins-configuration.xml file.

At the runtime, the new changes in ks-plugins-configuration.xml file will be executed and updated, Auto prune plugin will be executed depending on its properties.

Auto-count Active Users component is used to calculate automatically the number of active users. A user is considered as an active user only when he/she often adds topic/post in Forum and his/her last post date satisfies with the interval time that is predefined.

For example, after 15 days if one user does not have any new post, he/she is not considered as an active user.

When Job Schedule Service runs, it will get values which are returned from Auto-count Active Users plugin component to identify the number of active users. This value is updated at Active Members information when viewing Forum statistics.

The properties of Auto-count Active Users plugin is configured in ks-plugins-configuration.xml file.

In details:

At Job Schedule Service runtime, Auto-count Active Users plugin component is called, then ks-plugins-configuration.xml file is executed, the component-plugin named RecountActiveUserJob will be referred to org.exoplatform.forum.service.conf.RecountActiveUserPeriodJob to calculate number active users.

 <component-plugin>
      <name>RecountActiveUserJob</name>
      <set-method>addPeriodJob</set-method>
      <type>org.exoplatform.forum.service.conf.RecountActiveUserPeriodJob</type>
      <description>add a RecountActiveUser job to the JobSchedulerService</description>
      <init-params>
        <properties-param>
          <name>job.info</name>
          <description>save the monitor data  periodically</description>
          <property name="jobName" value="RecountActiveUserJob"/>
          <property name="groupName" value="KnowlegedSuite"/>
          <property name="job" value="org.exoplatform.forum.service.conf.RecountActiveUserJob"/>
          <property name="repeatCount" value="0"/>
          <property name="period" value="7200000"/> <!- 2 hours->    
          <property name="startTime" value="+0"/>
          <property name="endTime" value=""/>               
        </properties-param>
        <properties-param>
          <name>RecountActiveUser.info</name>
          <description></description>
          <property name="lastPost" value="15"/> <!- users are active if have last posts in 15 day ->
        </properties-param>
      </init-params>
    </component-plugin>

The properties for Auto-count Active Members plugin are defined in property tag like below:

...
          <property name="jobName" value="RecountActiveUserJob"/>
          <property name="groupName" value="KnowlegedSuite"/>
          <property name="job" value="org.exoplatform.forum.service.conf.RecountActiveUserJob"/>
          <property name="repeatCount" value="0"/>
          <property name="period" value="7200000"/> <!-- 2 hours-->    
          <property name="startTime" value="+0"/>
          <property name="endTime" value=""/>     
...
         <property name="lastPost" value="15"/> 
 ...

In which:

With start and end time, you can give a specific date in format:yyyy-mm-dd HH:mm:ss.sss to define the start and end time for RecountActiveUserJob . Besides, active time information is also defined:

By default, the default properties can only be changed by editing its value in ks-plugins-configuration.xml file.

At the runtime, the new changes in ks-plugins-configuration.xml file will be executed and updated, Auto-count Active Users plugin will be executed depending on its properties.

Main action bar displays all main function buttons. The number of function buttons depending on the role of user login. Currently, the main action bar is only visible on the homepage. It disappears when you focus into other pages. But Show/hide main action bar is an option, you can configure the main action to be shown or hidden in all pages all the time.

The value is to determine to show/hide main action bar in Forum is true or false.

In case true,Main action bar is shown on all pages.

In case false, Main action bar is only show on the homepage.

This value is defined in portlet.xml file like below:

...
 <portlet-preferences>
  <preference>
	<name>showForumActionBar</name>
	<value>false</value> <!- true/false ->
	<read-only>false</read-only>
  </preference>
 </portlet-preferences>
...

In which:

Default forum setting includes settings set for new user account. It contains declarations of time zone, short date format, long date format, time format, max topic per page, max post per page and flag for showing forum jump or not. It's rather simple and user can change such settings by UI based function after that.

This configuration is declared in a file named "ks-configuration.xml". Its path is "tomcat source/webapps/ks-extension/WEB-INF/ks-extension/ks/ks-configuration.xml" if you are running tomcat and "project source/extension/webapp/src/main/webapp/WEB-INF/ks-extension/ks/ks-configuration.xml" if you are in developing phase.

In details:

...
 <external-component-plugins>
    <target-component>org.exoplatform.services.organization.OrganizationService</target-component>
    <component-plugin>
     ...
      <init-params>
        <properties-param>
          <name>user.profile.setting</name>
          <description>set default user profile</description>
          <property name="timeZone" value="GMT"/>
          <property name="shortDateFormat" value="MM/dd/yyyy"/>
          <property name="longDateFormat" value="DDD,MMM dd,yyyy"/>
          <property name="timeFormat" value="hh:mm a"/>
          <property name="maxTopic" value="10"/>
          <property name="maxPost" value="10"/>
          <property name="isShowForumJump" value="true"/>
          
        </properties-param>
      </init-params>
      
      
    </component-plugin>
  </external-component-plugins>
...

In which:

IP logging is the IP of the computer which is used to connect Internet and do action in Forum. For example, when users add a topic or post in Forum, their IP address can be saved enclosing with their entry. Only the administrator can view that IP information.

However, get and save IP information is an option. The supper administrator can determine whether to get and save IP information or not.

The value is to determine to get and save IP enclosing with post in Forum is true or false.

In case true, the IP is gotten, saved and shown enclosing with post.

In case false, the IP is not gotten and saved.

This value is defined in portlet.xml file like below:

...
 <portlet-preferences>
  <preference>
	<name>enableIPLogging</name>
	<value>true</value> <!-true/false ->
	<read-only>false</read-only>
	</preference>
  </portlet-preferences>
...

In which:

The administrator can determine whether to get or save the IP logging or not by simply editing the value of this portlet preference in portlet.xml file with two optional value true or false.

This feature defines how the links are generated in the Forum application. You can choose to use ajax or not.

This article will explain how to configure the ajax setting for the forum portlet.

The setting is called useAjax and is defined in portlet.xml file below:

<preference>
 <name>useAjax</name>
 <value>true</value> <!--true/false -->
 <read-only>false</read-only>
</preference>

By default, 'true' value is set. Because using Ajax will makes the speed of the Forum process fatser.

If you want to show the detail link to any forum/topic in the Forum Application, simply replace 'true' value by 'false', the Forum Application will be displayed with the detail link to the page that is being viewed.

	Note
	Since KS 1.2

The easiest way to configure bookmarkability of the forum urls is to use the UI. Go to the portlet Edit Mode, then go to tab "Options", then uncheck "Use Ajax" option.

The Initialization plugin component is used to define the default answers data in xml or zip file. It includes categories of question and that should be exported from a eXo Answers application.

When Answers Service starts, it will get values which are returned from Initialization plugin component to initialize the default Answers data.

FAQ is configured mainly in two files:

	Note
	For general KS configuration information, please refer to [KS Configuration| KS:KS Manual#Configuration] section

FAQ portlet has portlet preferences that you can configure to alter the behavior.

At runtime you can use the portlet EDIT mode to set the preferences :

Alternatively, you may want to configure the portlet in portet-preferences.xml file.

Default Portlet Preferences

As a reference, the default portlet.xml for FAQ application is:

<portlet-preferences>
  <preference>
    <name>display</name>
    <value>both</value> <!-approved/both ->
    <read-only>false</read-only>
  </preference>
  <preference>
    <name>SendMailAddNewQuestion</name>
    <value> </value>
    <read-only>false</read-only>
  </preference>
  <preference>
    <name>SendMailEditResponseQuestion</name>
    <value> </value>
    <read-only>false</read-only>
  </preference>
  <preference>
    <name>orderBy</name>
    <value>alphabet</value> <!-alphabet/created ->
    <read-only>false</read-only>
  </preference>
  <preference>
    <name>orderType</name>
    <value>asc</value>      <!- asc/desc ->
    <read-only>false</read-only>
  </preference>
  <preference>
    <name>enableAutomaticRSS</name>
    <value>true</value> <!- true/false ->
    <read-only>false</read-only>
  </preference>
  <preference>
    <name>enableVotesAndComments</name>
    <value>true</value> <!- true/false ->
    <read-only>false</read-only>
  </preference>
  <preference>
    <name>isDiscussForum</name>
    <value>false</value>
    <read-only>false</read-only>
  </preference>
  <preference>
     <name>pathNameCategoryForum</name>
     <value> </value>
     <read-only>false</read-only>
   </preference>
  <preference>
      <name>enableViewAvatar</name>
      <value>true</value> <!- true/false ->
      <read-only>false</read-only>
  </preference>
</portlet-preferences>    

FAQ is configured mainly in two files:

	Note
	For general KS configuration information, please refer to [KS Configuration| KS:KS Manual#Configuration] section

Mail templates use a specific syntax that you can use to create a customized email message:

Parameters:

eXo FAQ is a JCR based application. FAQ information is saved in eXo-JCR under FAQservice data directory.

Category is created from exo:faqCategory nodetype and defined to add data inside as:

System auto creates category home under FAQ application node when the first time launch application. All users create categories are the sub-category of category home.

The home category auto created here:

<tt> /exo:applications/faqApp/categories </tt>

In fact, sub category is also a category, we defined a mixin nodetype called mix:faqSubCategory* to allow add a node with the same type with category to a existing category. When a category is created this mixin nodetype will be mixed to that category.

Each category has a RSS child node that stores a RSS feed representing all question in this category as binary data type. node type exo:faqRSS

<tt> /exo:applications/faqApp/categories/ks.rss </tt>

Question home node creates from exo:faqQuestionHome nodetype that is defined as a child node of category. This node is containing all question node that created in side a category. Only question nodetype (exo:faqQuestion) can be added to question home.

The question home is created as a child node of category

<tt> /exo:applications/faqApp/categories/questions </tt>

Question node creates from exo:faqQuestion nodetype under question home. The answers, comments and attachments are defined as child node of question.

The question node create under question home

<tt> /exo:applications/faqApp/categories/questions/Question7364ba00c0a8014700bcf58acbbafae2 </tt>

Question support multilanguages, all other languages are storing as a child node of question and can be add to question via a mixin nodetype called mix:faqi18n

After added mixin nodetype mix:faqi18n to question, the nodetype exo:questionLanguageHome can add to question node and this nodetype will containing all languages node with nodetype exo:faqLanguage, all display properties of question are defined in exo:faqLanguage nodetype

Answer, comment and attachment are defined as child nodes of question node. Attachment is defined as a nt:file nodetype and storing directly under question node. Answers and comments are storing under answer home and comment home nodes

<tt> /exo:applications/faqApp/categories/questions/Question7364ba00c0a8014700bcf58acbbafae2/faqAnswerHome/Answer736e99dec0a8014701622a1157719bb4 </tt>

<tt> /exo:applications/faqApp/categories/questions/Question7364ba00c0a8014700bcf58acbbafae2/faqCommentHome/Comment736e99dec0a8014701622a1157719bb4 </tt>

Storing information for sort data as order by, order type, sort question by vote. Each user has a dedicate setting for display data in faq as they want, the default setting is used if user have never save a setting. Node type is exo:faqUserSetting

<tt> /exo:applications/faqApp/settingHome/userSettingHome/$username} </tt>

This place stores template for FAQ portlet. User can online edit this template in FAQ portlet to change layout, skins,... The template is storing in an nt:file nodetype under template home node

<tt> /exo:applications/faqApp/templateHome/nt:file </tt>

Storing information about banned IP address access forum. Node type is exo:banIP, exo:banIPHome

The banIP stores under ForumSystem node

<tt> /exo:applications/ForumService/ForumSystem/exo:banIPHome/exo:banIP <tt>

Storing information of each user, user profile is auto created by a listener when user register to organization service. Private message can be added to user profile as a child node. Node type is exo:forumUserProfile, exo:userProfileHome. Private message exo:privateMessage define as child node of exo:forumUserProfile

The user profile stores under ForumSystem node

<tt> /exo:applications/ForumService/ForumSystem/exo:userProfileHome/exo:forumUserProfile <tt>

Storing Statistic information of forum as number of posts, topics, users, active users, ... Node type is exo:forumStatistic, exo:statisticHome

The Statistic stores under ForumSystem node

<tt> /exo:applications/ForumService/ForumSystem/exo:statisticHome/exo:forumStatistic <tt>

Storing informations for setting the layout, email notify format and censor works. Node type is exo:administration, exo:administrationHome

The Administration stores under ForumSystem node

<tt> /exo:applications/ForumService/ForumSystem/exo:administrationHome/exo:administration <tt>

Category home is defined for stores all categories of forum, this node is a child node of ForumData node and only category nodetype can be added to category home. Node type is exo:categoryHome

<tt> /exo:applications/ForumService/ForumData/CategoryHome <tt>

Category (node type is exo:forumCategory) is a child node of category home, this nodetype defined to allow add child nodes as exo:forum and exo:forumRSS

<tt> /exo:applications/ForumService/ForumData/CategoryHome/Category736e99dec0a8014701622a1157719bb4 <tt>

Forum node is defined as child node of category and allowed add child nodes as Topic and RSS type. Node type is exo:forum

<tt> /exo:applications/ForumService/ForumData/CategoryHome/Category736e99dec0a8014701622a1157719bb4/Forum1622a1157719bb4736e99dec0a801470 <tt>

Topic nodetype is defined as child node of Forum and allowed add child nodes as Topic, Poll and RSS type. Node type is exo:topic, exo:poll

<tt> /exo:applications/ForumService/ForumData/CategoryHome/Category736e99dec0a8014701622a1157719bb4/Forum1622a1157719bb4736e99dec0a801470/Topica8014701622a1157719bb4736e99dec0 <tt>

Post nodetype is defined as child node of Topic and allowed add only attachment type child node. Node type is exo:post, exo:forumAttachment

<tt> /exo:applications/ForumService/ForumData/CategoryHome/Category736e99dec0a8014701622a1157719bb4/Forum1622a1157719bb4736e99dec0a801470/Topica8014701622a1157719bb4736e99dec0/Posta157719bb4736e99dec08014701622a1 <tt>

Tag is storing in formation about name, topic that tag added, number of user used this tag, number of tag in used. Node type is exo:forumTag, exo:tagHome

<tt> /exo:applications/ForumService/ForumData/TagHome/tag2a1157719bb4736e99dec0a801470162 <tt>

Defined BBCode that is using in forum, Node type is exo:forumBBCode, exo:forumBBCodeHome

<tt> /exo:applications/ForumService/ForumData/forumBBCode/$bbcodename} <tt>

Node type is exo:topicType, exo:topicTypeHome

<tt> /exo:applications/ForumService/ForumData/TopicTypeHome/topicType2ec0a801470162a1157719bb4736e99d <tt>