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
EPF Wiki is used by EPF Community: several process descriptions that are being developed by the EPF community are available online as wikis in the EPF Wiki Website:
- EPF Practices
- OpenUP, also available in Portuguese, Russian and Spanish
- Scrum
- XP, also available in Portuguese
Other EPF Wiki guides:
- EPF Wiki Installation Guide for Linux (Ubuntu)
- EPF Wiki Installation Guide for Windows
- EPF Wiki Development Guide
Contents
Creating the Main Administrator Account
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 accessible 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 an EPFC published site. To create one, select Manage > Sites > New Baseline Process.
You can create a Baseline Process from a server folder that contains an EPFC published site or you can upload a zip file containing an 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 abbreviations without special characters. For example, oup for a Wiki for OpenUP.
This will create an 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 Composer (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.
When baseline updates are very frequent, you might consider an additional step and that is to automate the procedure, see the section #Automating_Deployments
More information on creating and scheduling jobs can be found in the EPF Wiki Installation Guide.
What happens when a Wiki is updated
An 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 in a 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
Basic Operations: Checkout, Save, Checking and Undo Checkout
To edit a page select Edit from the toolbar located at the top of the page. A form is displayed where you can supply a checkout note. You can also select the version you want to edit. As default the last version is selected. If you select an older version now you are effectively rolling back changes.
Click the button Continue to create the checkout and open the WYSIWYG editor. You can now start editing the page. The checkout operation created a working copy of the original page so any changes you make will only be visible after you check in the file.
The first three buttons are important because these communicate with EPF Wiki back end. They are labelled Save, Checking and Undo Checkout.
To save intermediate changes you use Save. This will submit your changes to the working copy. You could now for instance close your browser to finish your work at a later date. Checking will update the Wiki with a new version of the page created from the changes you submitted. This ends the editing session of the page. Undo Checkout also ends the editing session but without updating the Wiki, the working copy is destroyed, any changes you may have made to it will be lost.
Linking Pages
To create a link to link to another page you select a piece of text and then click the link symbol. A form is then displayed where you can set the properties for the link. Currently it is not possible to select a page from a list or use a search from to find a page to create to a link. This implies that you will have to provide the URL for the page manually.
Tip: you can find get the link URL for the other page by navigating to it and then by selecting Copy Link Location from the right mouse menu of the View button on the top of the page.
Inserting Images
To insert an image you place the cursor where the image needs to be inserted and then click the image symbol. This will open a form where you can set the properties for the image. You will have to provide the image URL manually; it is not possible to select images from a list. See also #Uploading_Files_and_Images
Updating Non-HTML Content
Typically an EPFC created site also contains other content than HTML pages. There are also images and other binary files and these cannot be edited using EPF Wiki. So this means that to update this type of content you edit this off-line using the tools of your choice and then upload the changed files to the Wiki.
How to upload files is described in the next section #Uploading_Files_and_Images.
Submit will upload the content and redirect to the page with a list of uploads in reverse order of the creation date time, so your upload should be on the top of the list. To see the result of the upload you can click the first link. That will open the uploaded file in your browser.
Tip: copy the link location now, you will need it when you are editing pages that will link to or use this uploaded resource. Select Copy Link Location from the right mouse menu of the first link in the row of your upload resource.
Uploading Files and Images
You can upload files by navigating to the home page of EPF Wiki and then selecting Upload File from the Toolbox. This will open a form where you can set the properties of your upload.
- Type: Image | Document
- File: path to the file you want to upload
- Description
Creating Pages
To create a new page you can select New from the toolbar on any page in a Wiki. This will display a form where you can provide the presentation name and select a template from the list of templates.
- Click the radio button to select a template.
- By clicking on the name of a template you can see a brief description of the template.
- Click on View to open the template in a separate window and see what it looks like.
On Submit a checkout will be created and the WYSIWYG editor will opened and you can start editing the page.
User Management
EPF Wiki offers simple functionality for managing users. There are only three roles: main administrator, administrator and user. The administrator role is for process engineers. It has extra privileges for harvesting e.g. for creating new Wiki sites and to mark changes as harvested. For more information see the section on #Harvesting.
The main administrator has all privileges of an ordinary administrator and then some extra e.g. for deleting Wikis.
There is always a main administrator. This role is assigned to the first user account that is created. The role can be transferred to another user.
Administrators can assign the administrator role to other users. The administrator role can only be revoked by the main administrator.
Users can register using a valid email account. To promote a user, select Manage and then Users. The Actions column shows icons to promote (up icon) and demote users (down icon).
Harvesting
Harvesting is a manual step! There is currently no way to update the library automatically with Wiki changes. If you need and/or want this feature please vote for the Bugzilla, see 334612
Harvesting is an important part of the architecture of EPF Wiki. The EPF Composer and EPF Wiki are very loosely coupled, this is for example visible in the overview picture for the EPF Wiki architecture.
Harvesting basically consists of reviewing changes, new pages, uploads and updating the process asset library using EPF Composer.
To harvest changes from a certain Wiki start the Wiki and then select Manage. A page is now displayed with a number of tabs that allow you to review and harvest changes, comments, uploads.
For all content types it works basically the same with the following fields: Review Complete, Reviewer, Review Note. To assign a contribution to yourself click on the line in the column Reviewer, this way other process engineers can know you are harvesting the change. At any time you can use,update Review Note. The purpose of this field is to provide information for yourself and the contributor on how the change was processed. To complete the harvesting, you check the box Review Complete.
To review changes you can compare versions. Next to each link for a version in the list of versions there is a compare icon. You can click this icon to see the difference of that version to the previous version. The picture below shows as an example how differences are highlighted. Red strike through text for deleted text and green underlined text for added text.
To be able to perform these operations you need extra privileges. You can get these from someone else who is harvesting or from the main administrator. You can find out who these users are by navigating to the list of users, from the home page select Users. Privileged users have an extra symbol next to the name.
How users are assigned these privileges is described in section #User_Management.
How To
Create a Task Step
Creating a Task step is hard to do in WYSIWYG mode. You switch to HTML mode and change the HTML directly. Find the place where the steps are defined and copy paste the HTML to create a new step. You can switch to HTML mode by clicking on the HTML icon on the editor toolbar.
A Task step is defined with two divs, one of class stepHeading and of class StepContent. Copy and paste the HTML of an existing step to create a new one.
<div class="stepHeading"> [Step heading text] </div> <div class="stepContent"> <table border="0" cellpadding="0" cellspacing="0" class="stepTable"> <tbody> <tr valign="top"> <td>[Step content text] </td> </tr> </tbody> </table> </div>
Change standard texts: Welcome, About, Login, Help, Terms of Use, Privacy Policy
A number of texts in EPF Wiki can be changed, you probably want to change them directly after creating the first account.
From the home page select Manage and then click your email address 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.
Change the application name 'EPF Wiki'
The application name is defined in the environment files: production.rb, test.rb, development.rb. So in a production environment you should change the environment variable ENV['EPFWIKI_APP_NAME']
in the file production.rb. In this file you can also change other settings e.g. the reply address ENV['EPFWIKI_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 + '@eclipse.org', :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