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

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 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.

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

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

Basic Operations: Checkout, Save, Checkin 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, Checkin 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. Checkin 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 a 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. The 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

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 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.

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.

Harvesting

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

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

1. Application name
2. 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 + '@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