Notice: This Wiki is now read only and edits are no longer possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.
EPF Wiki User Guide
If you have any questions about this guide or EPF Wiki please use the Eclipse Process Framework Project Developers List
Information on installing EPF Wiki is in EPF Wiki Installation Guide
Contents
Setup
After you install EPF Wiki and you have started your Web server, you can access EPF Wiki using your Internet Browser. EPF Wiki will display a form where you can create the first, main administrator account.
The creation of this account, will also create a Wiki called Templates which purpose is to provide templates for creating new pages to other Wikis. This special Wiki is not accessisble from the home page but you can find in the list of Wikis by selecting Manage from the home page.
Creating a Baseline Process
Wikis are created and updated using Baseline Processes. A Baseline Process is just a EPFC published site. To create one, select Manage > Sites > New Baseline Process.
You can create a Baseline Process from a server folder that contains a EPFC published site or you can upload a zip file containing a EPFC published site. It is recommended to upload your sites using FTP or SCP to the server folder and not use the upload functionality of the EPF Wiki web site because this puts a considerable load on the web server.
Make sure that a server folder or zip file does not contain sub folders. Or, put differently, make sure that index.htm is in the root of the folder you upload using FTP or SCP or is in the root of the zip file you upload.
Using technical abbreviations with version information for your Baseline Processes will make managing sites easier. Use for example OUP_1.0_RC4_20070725 for the file name of the zip file or folder name for OpenUP 1.0 release candidate 4 with build id 20070725.
Creating a Wiki
Create a Wiki with Manage > Sites > New Wiki.
The folder name will be part of URL so it is recommended to use abbrevations without special characters. For example oup for a Wiki for OpenUP.
This will create a empty Wiki site. You now can create a job to update the Wiki with a Baseline Process. This is described in the following section #Updating a Wiki. After having updated the Wiki with a Baseline Process you should be able to find a link to the Wiki on the Home Page. You should now be able to see the EPF Wiki toolbar on each page. The examples below show that the toolbar looks exactly the same in EPF and Rational Method Compser (RMC) created sites.
For sites created with EPF
For sites created with RMC
Updating a Wiki
Select Manage > Sites > [name of the Wiki]. This will display information on that Wiki. Select the link Select a Baseline Process and then select a Baseline Process from the list. Click Ok to confirm the update.
Typically the update will be performed by a scheduled task or cron job that runs job_daily. Alternatively you can choose to click Update Now to do the update immediately from the Web site. Depending on the number of pages this approach is fine. For large published sites it is recommended to use a scheduled task or cron job.
More information on creating and scheduling jobs can be found in the EPF Wiki Installation Guide.
What Happens when a Wiki is updated
A often discussed topic is what happens, or should happen when a Wiki is updated with a new Baseline Process. What happens with the Wiki changes?
Changes remain active or are overwritten depending on the harvesting status of the change. The harvesting is described in more detail ina separate section #Harvesting. If a change was marked as harvested, it is overwritten. The implicit assumption is that if a change has been marked as harvested, the library has been updated with the change and the change is part of the new Baseline Process that is being deployed.
Another thing that happens is that email notifications are send to all users that contributed content (changes, comments, uploads). An example of such a notification is below.
Editing Pages
Checkout
Checkin
Undo Checkout
Creating Pages
Harvesting
Tips and Tricks
Customization Options
Standard Texts
A number of texts in EPF Wiki can be changed, you problably want to change them directly after creating the first account.
From the home page select Manage and then click your email adress displayed on the right side of the toolbar. This will display your account details and will present links to the texts you can change:
- Welcome
- About
- Login
- Help
- Terms of Use
- Privacy Policy
If you do not want a Terms of Use of Privacy Policy for your site you can clear those texts. This will also remove the links in the footer to these pages.
Application Name
- Application name
- no-reply address
Automating Deployments
If you are doing updating and/or creating Wikis regularly it is recommended to automate the procedure. The code snippet below shows an example on how this can be achieved. This snippet can be added to the job_daily method in generic.rb. It will create or update Wikis using zip files that it finds in the folder ../../auto_deploy
.
The script uses the zip file to derive the folder name for the Wiki. The text before the first underscore character is assumed to be the name of the folder of the Wiki. If a Wiki with that folder name exists, it is updated, otherwise the Wiki is created.
So if your zip file is named oup_15_20080821.zip
this will update the Wiki located in folder oup
. If a Wiki with that folder name does not exist, it will create the Wiki. The Wiki will then be update with a Baseline Process that it creates from the content in the zip file. The Baseline Process will be stored in the folder oup_15_20080821
# do auto deployments d = File.expand_path('../../auto_deploy', RAILS_ROOT) if File.exists?(d) entries = Dir.entries(d) - ['.', '..', 'compare', '.svn'] puts("Doing auto deployments of #{entries.join(', ')}.") entries.each do |entry| basename = entry.gsub('.zip', ).downcase if !BaselineProcess.find_by_folder(basename) puts "Creating Baseline Process \"#{entry}\"" bp = BaselineProcess.new(:folder => basename, :title => basename, :user_id => cadmin.id) File.makedirs(File.dirname(bp.path2zip)) puts("Copying to #{bp.path2zip}") File.copy("#{d}/#{entry}", bp.path2zip) bp.unzip_upload bp.save! #puts "Creating Baseline Process \"#{entry}\"" name = entry.split('_').first.downcase wiki = Wiki.find_by_folder(name) if !wiki puts "Creating Wiki \"#{name}\"" wiki = Wiki.new(:folder => name, :title => name, :user_id => cadmin.id) FileUtils.rm_rf wiki.path if File.exists?(wiki.path) wiki.save! end update = Update.create(:wiki_id => wiki.id, :baseline_process_id => bp.id, :user_id => cadmin.id) update.save! update.do_update else Notifier::deliver_email(User.find_central_admin, "Could not auto deploy #{entry}", [],"<p>Hi #{cadmin.name},</p><p>The zip file \"#{d}/#{entry}</p>\" failed to auto_deploy because a Baseline Process with the exact same derived folder name \"#{basename}\" already exist. You rename the zip to make it unique for the deployment to succeed!</p>") end end end
Using a LDAP server to authenticate users
If you want to use a existing LDAP server to authenticate users, you can do so by replacing the login method in user.rb with a method similar to one below. The example below assumes you are switching from email based to LDAP based authentication and it tries to match the accounts using the email address.
def self.login(account, password) logger.info("Checking un/pw using basic authentication") user = nil treebase = "DC=eclipse,DC=org" user_filter = Net::LDAP::Filter.eq( "samaccountname", account) op_filter = Net::LDAP::Filter.eq( "objectclass", "organizationalPerson" ) ldap_con = Net::LDAP.new( {:host => 'eclipse.org', :port => 389, :auth => { :method => :simple, :username => account + '@groupinfra.com', :password => password }} ) if ldap_con.bind logger.info("ldap conn success for account #{account}, performing ldap search for details") entry = ldap_con.search( :base => treebase, :filter => op_filter & user_filter)[0] logger.info("Search for account in EPF WIki database") user = User.find_by_account(account) if !user logger.info("User #{account} does not have an EPF Wiki account?") user = User.find_by_email(entry.email) # we are switching from email based to ldap based authentication if !user logger.info("User #{account} does not have an EPF Wiki account! Creating account based on retrieved ldap server data!") user = User.new(:account => account, :email => entry.email, :name => entry.displayname) user.password = user.password_confirmation = password user.account = account user.i_agree_to_the_terms_of_use = "1" user.hashed_password = hash_pw(user.password) if user.password if user.save logger.info("Succesfully created account: #{user.inspect}") else logger.info("Failed to create account #{user.errors.full_messages.join(", ")}") Notifier::deliver_email(User.find_central_admin, "[#{ENV['EPFWIKI_APP_NAME']}] Error creating account using data from ldap server!",[], "#{user.errors.full_messages.join(", ")}") user = nil end else Notifier::deliver_notification([User.find_central_admin], "We have a match by email #{user.email} for #{account}!", , "#{account}", ENV['EPFWIKI_HOST']) end end user.email = entry.mail # TODO user.department = entry.department # TODO user.telephonenumber = entry.telephonenumber # TODO user.location = entry.l # TODO user.mobile = entry.mobile # TODO user.employeeid = entry.employeeid # TODO user.dn = entry.dn # TODO user.company = entry.company user.save! end return user end