INTRODUCTION

    SimpleWiki is your answer for project organization hosted right in your JIRA instance.

    Projects always accumulate a myriad of notes, documentation, and clutter. Rather than managing separate sites or sharing documents across separate products like Microsoft Sharepoint, or Confluence, keep your project planning and issue management local in JIRA.

    Just install the add-on, and you're ready to go. No extra configuration, or separate infrastructure is necessary.

    Pages use existing JIRA Markup, the same you already use for writing JIRA Issues, and also plays nicely with the Atlassian Wiki Editor, making it a breeze to create content.

    INSTALLING SIMPLEWIKI

    The SimpleWiki plugin doesn't require any special configuration to work. Simply install it via the Atlassian Marketplace, or one of the other methods detailed below, and you're ready to use it the moment the install finished.

    COMPATABILITY WITH JIRA

    The SimpleWiki add-on is compatible with Atlassian JIRA 6.0 and updwards.

    INSTALLING VIA ATLASSIAN MARKETPLACE

    1. Go to the SimpleWiki Atlassian Marketplace page.
    2. Buy or evaluate the add-on with a free 30 day trial.
    3. Login to your JIRA account, if required, to proceed installation of the add-on. The license key is automatically configured into the add-on configuration for free trial licenses.

    INSTALLING VIA JIRA PLUGIN MANAGER

    1. In JIRA, click on the Admin gear, and find and click the "Add-Ons" link.

      The Find New Add-ons page is displayed.

    2. Search the Marketplace for 'Wiki' as the search phrase.

    3. Buy the add-on or start the free trial for 30 days.
    4. Login to your JIRA account, if required, to proceed installation of the add-on. The license key is automatically configured into the add-on configuration for free trial licenses.

    INSTALLING MANUALLY

    Use manual install if you have a specific version of SimpleWiki downloaded from the marketplace or sent by some other file sharing method:

    1. In JIRA, click on the Admin gear, and find and click the "Add-Ons" link.

      The Find New Add-ons page is displayed.
    2. Once the "Find new add-ons" page shows, go to Manage add-ons


    3. Click and navigate to the jar file that you already have.
    4. Click Upload, and wait for the confirmation dialog that the install finished.
    5. Buy the add-on or start the free trial for 30 days.
    6. Login to your JIRA account, if required, to proceed installation of the add-on. The license key is automatically configured into the add-on configuration for free trial licenses.

    GETTING STARTED

    Browsing for Pages

    Each JIRA Project has it's own Wiki section. To get to each of your Wikis, use the "Wiki" dropdown in the main JIRA header.

    Simply click on "Browse Projects", and this will lead to a project list, similar to the one JIRA has for issues. It provides a quick overview of the JIRA projects you have access to, and how many pages or topics it contains.

    Select a project, and you'll arrive at the Wiki for the selected project.

    Note:

    If the Wiki dropdown in the main header already contains the project you want in the "Recent Projects" section, you can simply click it there, and it will lead to the Wiki of that project as well.

    The starting point for each Wiki is the "Home" screen. It shows your favorite pages, favorite topics, and recently viewed pages.

    The first time you visit this screen, you won't have any of those of course. To create a page, follow the steps in the next section.

    The other sections within the wiki are:

    Topics
    Allows you to manage topics. See the Topics Section for more info

    Pages
    Allows you to manage all the pages in this project. See the Manage Pages Section for more info

    Archives
    Allows you to manage all the archived pages. See the Archived Pages for more details

    Tags
    Gives you an overview of all the labels in use on pages. See the Labels Section for more info

    Activity
    Provides an activity stream of all the wiki related changes in this project. See the Page/Project Activity Section for more details

    Creating a Page

    New Pages can be added from the "Home" screen, and the "Pages" screen, via the "Create Page" button.

    Clicking the button brings up the "Add New Page" dialog, which allows you to specify a name and a key for the page.

    The name is a user friendly title of the page. This is what shows up as the header of each page, and what you see whenever a page is referenced somewhere. It can contain any characters you wish.

    The key of the page is similar to an issue key. This will act as the underlying identifier for the page and will be used in the url. Thus a user can bookmark a page, and not be affected by the title of the page changing.

    Note:

    The key must be unique within the project, and after you've set the key for a page, it cannot be changed without recreating the page and losing the history & past versions of the page.

    Once you've entered a name and key, clicking the submit button creates the page, and it will immediately show up in the "Pages" list.

    Wiki pages can have labels, files, and permissions, which you can set separately, after the page is created.

    Viewing a Page

    To view a page, simply navigate to the project wiki as described above, and then find the desired page in the "Home", or "Pages" screen, and click on the title.

    Note:

    Alternatively, you can find some of the recent pages in the Wiki header, or on the "Home" screen.

    Once you've navigated to a page, you'll see the page content, similar to this:

    The page itself consists of 3 sections.

    Page header
    Shows you the title, labels, who created the page and last edited it, as well as common actions.

    Page body
    The actual written content of the page, along with embedded images, and so forth.

    Comments
    All the comments attached to the page.

    Additionally, you'll notice the sidebar, which allows you to interact with the page in various ways like setting permissions, or adding watchers, as well as navigate to sub-sections of a page, like attached files, past versions, access log, and more.

    Editing a Page

    To edit the content of a page, click the edit button from the page header

    or alternatively use the actions dropdown from the "Pages" list

    Either one will lead you to the edit screen, which allows you to change the title, as well as the content of the page.

    Wiki pages support standard JIRA Markup and macros, so you can insert {code} blocks, {panel}'s, and {noformat} with ease, style content with the same formatting options already available for JIRA issues, and embed images and files using the same syntax as JIRA. For a full reference of what markup is available, simply click on the question mark, and it will bring up the JIRA Markup help.

    Additionally, you can mention users via @user syntax, and link to pages using #page syntax.

    Since you're writing content in markup, you can easily preview what your page looks like by clicking on the preview button.

    This will toggle the page to preview mode so you can see what it looks like. Click on "Exit Preview", to return to edit mode.

    Once you're satisfied, click "Save" to save your changes, and you'll be returned to viewing the page.


    MANAGING PAGES

    Finding Pages

    To find pages, you can always look in the "Pages" list. This list contains all pages within the project that are not currently archived.

    The list of pages supports pagination, so if you have many pages, you might have to navigate to some of the sub-pages within the list to find your page.

    The list can be filtered to only show pages you've marked as a favorite, pages where you are the owner, or pages that have been updated recently (within the past 7 days). Selecting one of the filters automatically reloads the page list based on the filter selected.

    Alternatively, you can also search for pages using the search field. Searching will return any page where the title or the page content matches your search query.

    You can combine searches with filters. For example, you can search for pages with specific keywords, and then filter the result to only show the ones recently updated.

    To clear a filter, simply click on the "All Pages" option again.
    To clear a search, click the small "x" icon to clear the field.

    Deleting a Page

    Deleting a page can be done either from the page itself, via the sidebar

    Or from the "Pages" list, via the actions dropdown.

    Deleted pages are removed immediately (upon confirmation of course), and all past versions, as well as history/activity entries are removed from the activity stream, with the exception of the actual delete event. Any files attached to the page are automatically deleted as well.

    Note:

    Deleting a page is permanent. There is no undo for this.

    Copying a Page

    To copy a page, navigate to the "Pages" screen, and select the Copy option from the actions menu.

    This will bring up the copy page dialog, which allows you to specify a new name and key for the copied page.

    Just like with page creation, the key must be unique.

    Note:

    By default, only the page content itself is copied. This means any labels applied to the page, comments, or files attached to the page are excluded from the copied page. This also means that any files or thumbnails mentioned in the page could now be dead links.

    You have the option to include labels or files, by simply clicking the appropriate checkbox when performing the copy.

    Changing the Page Owner

    The owner of a page is typically the user that created it intially. The user that owns the page always has permissions to view & edit the page, event if that user would be excluded from such actions when setting page permissions.

    This makes it important to be able to change the owner of a page, especially for private pages that only specific users should have access to.

    To do that, select the change owner action either from the "Pages" list actions dropdown

    or from the sidebar when viewing the page

    The dialog that shows up should be familiar, as it looks and functions pretty much the same as when you reassign a JIRA Issue. Type the user's name, and select it from the autocomplete dropdown. Once you're satisfied with the selection, click the "Assign" button, and the page owner is immediately changed.

    Favorites & Archives

    Pages can be marked as favorites, or archived.

    Marking a page as a favorite is on a per-user basis, and means only that user has the page as a favorite. Favorite pages show up in your "Home" screen for each Wiki, and make it easy to return to a page. Any user can mark a page as a favorite, as long as they have access to it.

    Marking a page as a favorite can be done from the "Pages" list, by clicking the star icon that appears when you hover to the left of the page title.

    Or you can do the same when viewing a page, via the star button in the page header.

    To unfavorite a page, simply follow the same steps, and click the favorite buttons again, and the page will be removed from your favorites.

    Archiving a page is done on a global basis, and applies to all users the same.

    Archiving a page removes that page from the "Pages" list, and places it in the "Archives" section.

    Archiving a page is a great way to declutter your pages, and tuck away old ones, or infrequently used pages, without losing their content.

    Archived pages don't show in the activity stream any longer either if they are changed.

    Tags/Labels for Pages

    To organize your wiki a bit, SimpleWiki gives you the ability to add labels to pages. Each page can have an arbitrary amount of labels applied to it. You can use any label currently in use within JIRA, or add your own labels.

    To add a label to a page, either navigate to the page itself, and click the edit button in the label section

    Or on the "Pages" list, hover the mouse over one of the pages, and you will see an action for "Add Labels".

    Both actions will bring up the labels dialog, which allows you to either select one of the existing labels, or simply enter a new one.

    The field for labels is free-form, and provides type-ahead. So the moment you begin typing, it will automatically perform a search against the existing labels. Hitting the enter key on your keyboard will select one of the labels, or insert your new label.

    Labels are applied immediately, and you don't need to specificially "save" your changes.

    Removing a label follows the same steps. Bring up the labels dialog, and remove a label by clicking the small "x" icon within it, or select it and hit the backspace key on your keyboard.

    Labels in use within the Wiki are automatically aggregated into the "Tags" section of the wiki. This shows you all the labels in use, and how many pages have a label applied to them.

    Clicking on one of the labels will show you specificially which pages

    Page Permissions

    Pages within a wiki are generally open to anyone who has access to the JIRA project. Sometimes however, you have a page with sensitive information. Things like shared credentials, admin specific notes, and so forth. In those cases, you want to protect your pages.

    To change permissions on a page, click the lock icon from the "Pages" list

    or the permissions button from the page sidebar.

    This will bring up the permissions dialog, allowing you to specify a set of JIRA groups or JIRA roles that should have access to your page, and what kind of access you would like to grant them.

    Read access allows a user to view the page contents, as well as attached files. Users with only read access cannot change the page content, or attach new files, or restore old versions. They can however still comment on the page, view the history, watch the page, or copy the page.

    Users with write access can perform any action against the page.

    Permissions for groups are based on a hierarchy, this means if you specify read-only access for the "users" group, any group above that will have full access. If you specify read-only access for the developers groups, then only the admin group would have read access.

    Permissions for roles apply only to users with a given role.

    There are 2 special cases to permissions.
    1) users in the JIRA Administrators group always have read/write access to a page
    2) the owner of a page always has read/write access to a page. This is to prevent accidentally locking out the owner.


    WIKI PAGES IN DETAIL

    Using Macros

    To create more content rich pages, you can utilize all of the built-in JIRA Markup and macros.Some of the common macros are:

    {panel} {noformat} {code} {quote}

    Some of the common markup to use includes:

    • headers
    • bold & italics
    • line breaks
    • bulleted and numbered lists

    For a full reference of all the markup, click on the question mark button when editing a page.

    If you want the ability to create even richer content, we have another plugin in the marketplace called Quick Suggest Macros , which adds many more content macros, like:

    status badges messages icons better issue links and issue tables for example

    In addition, it provides a convenient autocomplete function for all macros. Simply type a curly brace { and the autocomplete dialog comes up, allowing you to select which macro to insert, and then allows you to customize the macro via autocomplete dialog.

    The Quick Suggest Macros plugin works within SimpleWiki as well as JIRA itself.

    There is also a free plugin available from the Atlassian Labs team called Wiki Editor for JIRA , which creates a toolbar to insert macros. It is compatible with SimpleWiki as well.

    Linking Pages

    Pages can be linked together using a markup syntax of: [!pagename]

    For your convenience, we've added an autocomplete function similar to user mentions. Simply start typing a pound sign and the name of a page, like this: #page
    And you will see a dropdown show up with suggestions of pages that match the title you're entering.

    Select the page you wish to link to, and the markup is atuomatically added in-place.

    This works with within pages, and within any issue field that supports wiki rendering. (typically the issue description, and comments).

    File Attachments

    Just like JIRA issues, Wiki pages can have files attached to them.

    To attach a file to a wiki page, first navigate to the page, and then click on the file section in the sidebar

    This will show you all the files currently attached to a page. You can switch between a details view and a gallery view by using the buttons in the header.

    Either drag & drop a file from your desktop onto the area at the top, or click on the "Upload" button to bring up a file picker dialog.

    Uploading a file with the same name as an already existing file behaves the same as JIRA. The existing file will be overwritten, and versioned, thus the newest version always shows. If you delete a newer version of a file, the older version will show again.

    To delete a file, simply click on the trash icon next to the file.

    Deleting a file is permanent, and cannot be undone.

    Note:

    If you delete a page, attached files are deleted along with it.

    Embedding Images & Files

    Within the page content, you can reference files attached to the page, and embed images and thumbnails into the page itself.

    To accomplish this, edit the page, and use the filename in one of the macros for embedding files. The various macros and their syntax are:

    link to an attached file embed an image embed an image thumbnail image options for size ..etc

    you can also reference files & images from remote sites by using a full URL.

    image from a remote url

    Commenting on Pages

    Commeting on pages works the same as commenting on a JIRA issue. Comments always show below the page content, to keep both in context to each other.

    To add a comment, navigate to the page you wish to comment on, and click the "Comment button"

    Enter your comment into the text area, and click the "Add" button

    Just like comments in JIRA issues, you can mention users, embed images, and use macros. You can also preview your comment by using the small preview button

    Editing or deleting a comment can be accomplished by hovering over a comment, which will make the edit and delete button visible.

    Watchers & Notifications

    If you want to be kept up-to-date on changes to a page, you can add yourself (and others) to the watchers list of a page. The functionality is the same as JIRA issues.

    Click on the start/stop watching button to add/remove yourself from the watchers list.

    Or click on the watchers icon in the sidebar, to see who is watching the page, and add/remove other users.

    Anytime the page changes, all users in the watchers list are notified via email of the change.

    Note:

    The email notifications are dependent on your JIRA notification settings. This means, if you don't have any notification schemes setup, no emails will be sent.

    Page Activity

    Anytime a page changes, an activity entry is created for the page. The entire activity log for a page can be reviewed by selecting the "Page Activity" screen from the sidebar of a page.

    The activity screen shows you a quick overview of each action that was taken on the page, and who performed the action. Activity items can be expanded for more details.

    To narrow down the list, you can filter by date range, and user.

    Note:

    Generally, all actions on a page add an entry in the activity log, with the exception of marking a page as a favorite, permissions changes, and changing the watchers of a page. Those are excluded from the activity log.

    Past Page Versions

    Anytime the content of a page changes, a new version is generated. Each page keeps track of the past versions, and allows you to view past versions, as well as revert back to a past version.

    Click on the "Past Versions" icon in the page sidebar, to bring up the versions screen.

    From there, select a desired version on the right side, and you can see the contents of the page from that version. Clicking on the "restore" button will revert back to that version.

    Note:

    Versions only encompass the actual page content & title of a page. This means comments, labels, attached files, and page permissions live outside of the versions, and they remain as they currently are, even if you revert back to a version.

    Page Access Log

    Each page keeps track of which user accessed it and when. The primary purpose of that is to maintain a list of recent pages for each user. The secondary purpose is to maintain an auditlog that allows admins to review who has seen a page and who hasn't.

    The page sidebar contains an icon to view the Page Access Log

    The access log itself shows the date & time of the visit, the user, and the IP they came from. For public pages, the log can contain entries that only have an IP and no JIRA user associated, since the page is accessible anonymously, by the public.

    The list can be filtered by date, user, and IP, using the provided filter fields.


    DASHBOARD WIDGETS

    SimpleWiki comes with 2 dashboard gadgets, that provide easy access to a list of pages, or a specific page, directly from one of the JIRA dashboards.

    Pagelist Widget

    The pagelist gadget does exactly as the name implies, it shows a list of pages on the dashboard. When you add the gadget, you configure it to show pages matching your specific criteria, like project, a specific owner, or pages matching the labels you specify.

    Once configured, the gadget shows the list of matching pages, providing quick access to those pages.

    Some common uses include easy access to specific documentation like QA steps, introductions for new users, pages related to upcoming releases, and so forth.

    Single Page Widget

    The single page gadget allows you to show the contents of a page directly on the dashboard, making it perfect for welcome messages, as well as lead-in for documentation, announcements, contact lists, or important upcoming dates.

    Configuration of the gadget is as simple as selecting a page from a project.

    Note:

    In order to see the page, a user must have permissions to the page. This means if you point the gadget to a page that only admins can see, non-admins will receive a permissions error.

    Related Pages

    The issue screen shows a section in the right side for Related Pages.

    These are pages mentioned within this issue, or pages where this issue is mentioned.


    MISC

    General Settings

    SimpleWiki exposes a few general / global settings.

    These apply to all projects and all users, and are managed by the JIRA admin. General settings can be configured via the SimpleWiki Settings on the "add-ons" screen.

    Available settings include:

    - JS Error Logging Whether SimpleWiki should keep a log of all UI / Javascript errors encountered. By default this is enabled, and all errors are placed in a log on the JIRA server. The main purpose for this is for diagnostics & debugging purposes, to make it easier to track down issues you encounter when submitting a support request.

    Note:

    The log file does not contain any sensitive information, and the log file only lives on your server. We (the plugin developers) have no access to this, unless you specifically submit it to us as part of a support request.

    - Show Related Pages Section Whenever an issue is mentioned in a Wiki page, the page is associated with the issue. If this setting is enabled, the issue screen shows a new section for Related Pages (Wiki pages where this issue is mentioend), in the right side.

    - Show Recent Projects & Number of recent projects to show This setting determines whether the main Wiki dropdown in the JIRA header shows a section for Recent Projects, and how many recent projects should be shown. The default is "yes", and up to 5 recent projects.

    - Show recent pages & Number of recent pages to show This setting determines whether the main Wiki dropdown in the JIRA header shows a section for Recently Viewed Pages, and how many recent pages should be shown. The default is "yes", and up to 5 recent pages.

    - Page access log cleanup interval Since each page tracks page usage, and this log could potentially be huge, the plugin cleans up after itself in the given interval. It automatically discards access log entries older than the specified interval. The default is 10 days.