Actual Notes Jira add-on documentation

Thank you for discovering our add-on. We will try to offer your new and lite experience in working with Jira "outside of a Jira"!

What it actually means? Well, it means that you can keep be active in Jira projects even outside of Jira boundaries by using your Evernote notebooks as a source for business ideas and proposals for project issues. It's easy - just install an add-on and try it..

Demo Image

Introduction

Aim

What is Actual Notes plugin for? Well, Actual Notes allows one to perform daily activity out of Jira via private Evernote notes. The plugin adresses the following needs:

  1. Daily activity on issues.
  2. Turn your notes into comments.
  3. Keep your evernote data actual to issues state by adding new comments from new and updated notes

Functions

Main functions of Actual Notes plugin:

  1. Manage evernote credentials (activation of evernote credentials in a Jira is performed by admin and editing and authorizing is performed by owner of account itself).
  2. Getting updates from Evernote service for new and edited notes in automatic scheduled mode
  3. Commenting on issues from behalf of Jira user from its Evernote notes automatically using notes content.

FAQ

  • How does it work?

    Actual Notes plugin contacts with Evernote services for synced notes data. Once receieved it processes each note seeking any relation with Jira issues. Any related notes will be used as a comments to target issue. Special schedulled service will submit comments from behalf of a Jira user which is also an Evernote Account holder. The sole person who defines note association with particular issue (task) is an Evernote account holder.
  • How the link is established? Is Actual Notes plugin so smart to distribute all notes among issues?

    Of course, the plugin is not an AI. There are several basic rules how to map note to particular issue. 1. Place tag with issue key onto note and that's enough for Actual Notes add-on services to find proper candidate issue to comment into. 2. Start a title of a note with an issue key. For example: "AN-606 Implement rooms renderer component" Once processed, this note will be commented in issue AN-606 if such a project and issue are exist. Additional requirement is a proper Jira user access permissions for a project.
  • Is it secure?

    An add-on uses your developer or API key to talk with Evernote services. It does not expose them to other Jira users. Also, It does not require your Evernote account password or any other data. Currently it just receive updates from your notebooks. Hence once broken or hacked it cannot delete, modify or corrupt somehow your private notes data within your Evernote account.
  • Can I keep multiple Evernote account for single Jira user?

    No, now Actual Notes add-on allows only to create single Evernote Account per Jira user.

Requirements

There is no such a long list of pre-conditions to start to work with our add-on. Here it is:

  1. Java 6-8
  2. Jira of versions 6.1.x - 6.7
  3. Evernote account(s) with either Developer Token or Consumer Key and Secret Key activated for Production environment of Evernote service.

Glossary

Terms

Before exposing any details of this lite add-on lets familiarize with some terms. They will help one to understand basic rules and functions of Actual Notes plugin.

  1. Evernote. The Evernote's company flagship product which allows users to create a "note" which can be a piece of formatted text, a full webpage or webpage excerpt, a photograph, a voice memo, or a handwritten "ink" note. Notes can also have file attachments. Notes can be sorted into folders, tagged, annotated, edited, given comments, searched, and exported as part of a notebook. Evernote supports a number of operating system platforms (including OS X, iOS, Chrome OS, Android, Microsoft Windows, Windows Phone, BlackBerry, and webOS) and also offers online synchronisation and backup services.
  2. Note. Note is literaly a virtual sheet of paper for storing your private (or public, why not) data, business ideas, To-Do lists, poetry, image or other multimedia data.
  3. Notebook. Notebook is an entity which groups your notes by some generalizing attribute. Evernote allows to create unlimited set of notebooks within user's account. You can place your Jira specific notes in a one notebook not affecting others.
  4. Comment. Comment is a Jira User's proposal or question into particular issue. Comment is related to issue as one to one.
  5. Jira User (further will be referred as User). One that have account in particular Jira instance. Either admin or a common user from any group.
  6. Evernote Account. A record in a plugin config and a user's registered account in Evernote service. As a record in Actual Notes plugin Evernote Account contains user's Jira username, developer token and/or a pair of Consumer and Secret Key for requesting Evernote services for note updates.
  7. Developer Token. There are two ways to authenticate to the Evernote API, developer tokens and OAuth. Developer tokens provide instant access to your Evernote account via the API.
  8. API Key. An API key is what allows you to perform requests using OAuth mechanism. Actually API key implies a pair of a Consumer Key and Consumer Secret. You can request an API Key for SANDBOX environment and then request an activation for Production by submitting special Evernote form.
  9. Consumer Secret. Is a accompanying to consumer key character sequence. Both of them help plugin to start authenticating process which is needed to obtain Access Token from Evernote service. Having an access token key a Jira user Evernote Account is ready to receive updates.
  10. Access Token. Access token will allow the plugin to access Evernote on behalf of the user.
  11. Configuration. Structured data of Actual Notes plugin which allows it to provide its main functions: updates for fresh notes and managing Evernote Accounts. It consists of two main parts: set of Evernote Accounts and general Settings.
That's all for starting. Let's also look at roles of whose who will be working with Actual Notes plugin.

Roles

We can distinguish two types of users who will be working with add-on. They have common abilities but also exclusive rights, responsibilities and actions.

  1. User. A common role including both admin user and all other groups of user (developers, limited permission users etc.). User can see or modify only its own Evernote Account. Non admin user cannot activate its account to start receive evernote updates. He should contact any admin user to proceed.
  2. Admin User. A person who is capable of editing Jira settings, manage users is supposed to be an Admin User. This category of users are allowed to manage Evernote Accounts in Actual Notes plugin. The only action now is to activate/deactivate Evernote Account so it can request updates from Evernote Services. Admin user cannot see or modify Evernote Account of any user only its own account.
That is enough information that a common user should now in order to understand how manipulation with Evernote Accounts works in Actual Notes add-on. Concise enough, isn't' it?

Pages (Add-on screens)

Top Navigation Bar

This is actually not a screen but UI element of plugin. Main entry point for new user to start work with Actual Notes plugin. Here is an image below:
General configuration

General configuration

This screen allows to configure basic settings of plugin:

  1. Process rate (in minutes). Defines frequency of getting note updates and processing them for comments.
  2. Include comment footer. Boolean option. When turned on - places a special adding to the text of comment (applies only to new or updated comments once turned on)
  3. Footer Text.Defines a text to be appended to bottom of a comment text.

This page is available for admin users only. The image of a screen presented below:
General configuration

Evernote Accounts

Page allows to list all created Evernote Accounts within Jira and activate/deactivate them.

This page is available for admin users only. The image of a screen presented below:
Evernote Accounts

Create/Edit Account

Page allows either admin or a common user to manage its personal Evernote Account. Allowed actions are:

  1. Delete account. Click 'Delete' button to erase all credentials data.
  2. Save Always click 'Save' button to apply all changes.
  3. Request Access Token Action available when there are non empty Consumer Key and Consumer Secret present in credentials.
  4. Specify SANDBOX environment The sandbox is a separate instance of the Evernote service, designed as a safe environment for you to develop your applications without worrying about messing up your actual Evernote account or impacting Evernote production service. Usefulf for evaluation purposes.

This page is available for both admin and non admin users. The image of a screen presented below:
Create/Edit Account

Start Reindex Page

Page allows to make manual update for notes.

  1. Request Updates Get just fresh notes.
  2. Reindex Clear all old data and request all notes once again.
  3. Reset Clear all old data. Any obtained notes will be deleted from local storage. However no posted comments will be affected.

This page is available for admin users only. The image of a screen presented below:
Start Reindex Page

How to Start working with add-on

Working with add-on requires several steps:

  1. Obtain either developer token or an API key. Follow this page for developer token

    https://www.evernote.com/api/DeveloperToken.action

    or this page for API key (click top-right button on the page - GET AN API KEY)

    https://dev.evernote.com/doc/articles/permissions.php#
    Note. One can request Developer Token for Sandbox or Production service. For real projects and real notes one should get Developer token for Production service.
  2. Go to "Create or Edit Account" page. Click on top navigation bar button - Actual Notes then select item "Create or Edit Account". Fill in required fields: - Name of account - Developer token or Pair of Consumer and Consumer Secret Key. One can fill in both Developer and API key fields. But the plugin has a higher priority for API key when requesting updates from Evernote services. - Save all changes Create or Edit Accont Page
  3. In case using Consumer and Secret access key pair one should proceed for authorizing plugin via OAuth mechanism. Click on button Authorize for Access Token. There will be redirect on Evernote sign in form (in case user has not been logged in earlier) or directly on submit form. Authorize Form For Access Token
    Choose period for Access Token expirity and then proceed. You will be redirected back to your account. Choose expiration period for Access Token
    Once succeeded there will be label indicating expiration period of access token.
    Choose expiration period for Access Token
  4. In case using Developer token there is no additional steps required here.
  5. Just created Evernote Account is inactive by default. It could be activated only by admin user of Jira. Ask your admin to activate your Evernote Accounts to be ready to get and process updates for fresh notes. If you are an admin person, proceed for Evernote Accounts page for activating an account. Go to Actual Notes -> Evernote Accounts. Sample screen below:
    Choose expiration period for Access Token
  6. You've finished with configuring Actual Notes add-on. Well done!

Marking notes

Actual Notes uses simple set of rules when making decisions whether given note should be transformed into comment for issue or not and what the target isue is.

  1. Note having issue key (for example, AN-606) is a potential candidate for comment.
  2. Note title containing issue key in first position also trigger the plugin to process such note for comment.
  3. Note title have higher priority over tags. Hence note marked by issue key in title as AN-1 and in tags as AN-3 will be suggested as comment for issue AN-1.
  4. In case there will be no issue for key from title process keep parsing tags for other issue matches. First found issue will be candidate to place comment into and process will stop parsing other tags.
  5. It is not recommended to place issue keys both in title and in tags. It is also recommended to use a single issue key in tags. Because there is no agreed order on how tags will be arranged for given note and add-on just uses first tag which matches existing issue in Jira. Place keys of related but not target issues either in tail of a title or in note content.

Contact Us

We are glad to see you evaluating our plugin. Hope it leverage your daily activity on your favorite Jira projects! Feel free to contact us in free form via email: minibfg@gmail.com. You can propose your ideas, change requests or user stories, all questions and ideas will be met. Thank you!