Invoices. Installation and User Guide. Release date: GNU General Public License, version 2 Terms and Conditions apply

Transcription

1 Invoices Installation and User Guide Release date: GNU General Public License, version 2 Terms and Conditions apply 1

2 1. What is Invoices? 3 2. Requirements and Compatibility 4 3. License Activation 5 4. Installation 7 5. Configuration Invoices Templates Create and Manage Invoices Adding Payments for Invoices Expenses Integration with Finance Plugin CSV Import and Export Roles and Permissions Configuration Redmine Services Language Support Terms and Conditions Licensing

3 1. What is Invoices? Invoices plugin is a full-featured on-line billing and invoicing system for your Redmine. Create, track and export your invoices. Bill issues' time entries or, alternatively, create invoices from scratch with your custom quantities, prices and units of measure. The plugin is suitable for individuals and organizations, which work closely on clients projects, such as freelancers, software and service companies. The main feature of Invoices is the ability to bill on the basis of time spent on different activities or issues for your client (e.g. design, development, documenting, support on a specific issue), where the time spent is the value, which is reported by you or your employees on each particular case using the Log time feature in Redmine. There is also support for tracking expenses, which do not have time-basis nature, such as buying a license for third-party software solutions. These expenses are transparent for your client and expenses statuses (new, draft, billed, paid) allow you and your client to negotiate the necessity of these expenses for the client s project and track the payment status for agreed operations. Invoices plugin also allows you to take into account taxes and discounts and provides tagging system to track paid, canceled, draft and sent invoices. Invoices plays nicely with custom fields and has a support for CSV import and export. Each invoice could be downloaded as a PDF document and sent to the client within the Redmine. You can install our CRM plugin for this. If you use Finance plugin for bookkeeping, Invoices will enhance the transparency of your operations by creating relations between operations and invoices. Invoices pluigin was developed by RedmineCRM team as a separate plugin for Redmine project management system. RedmineCRM team is not affiliated with Redmine. 3

4 2. Requirements and Compatibility Invoices plugin requires the following prerequisites for its successful installation and operation: Redmine 2.3, 2.2, 2.1 CRM plugin (Both Light and Pro versions are compatible with Invoices plugin) Ruby 1.8.7, 1.9.2, 1.9.3, Databases: MySQL, PostgreSQL, SQLite Operating System: Linux, OSX, Windows Invoices plugin was tested in Opera, Chrome, Firefox, Safari and Internet Explorer browsers. a. Gem dependencies Plugin relies on certain Ruby on Rails gems, which should be installed automatically, but are mentioned here in case of any problems with Bundler and your environment. gem "prawn", "~> rc1" gem "money", "~> 5.0.0" 4

5 3. License Activation After the purchase of the Invoices plugin, please use your Order Number and Order to activate your license. This could be done through the License Manager section which is accessible on license_manager. The following steps will help you to register your Invoices copy: Figure 1. Step 1 Register an account on RedmineCRM website First, register on the To get to the registration page, click Sign In on the top pane and then click Register, and, finally, fill in the registration form. You can register your account with the address different from the address you specified in your order. Figure 2. Step 2 Enter your license number and order 5

6 After you registered successfully, visit License Manager section. It is accessible on Alternatively, click on your user name and select License Manager. Your license number is your order number and is 8-digits long. Order is the you specified during the purchase. Figure 3. Step 3 License has been activated. You can download plugin and As soon as you activate your license, you will be able to download the latest version of Invoices plugin. The license allows you to download updates for the lifetime. If you need older versions, please contact our support: support@redminecrm.com. You can follow the above steps to register any plugin you buy from RedmineCRM. Thank you for buying our plugins 6

7 4. Installation Step 1. Install CRM plugin. Both Light and Pro versions are compatible with Invoices plugin. You can download free version of CRM plugin from our site CRM Pro version could be downloaded from your License Manager after you activate the license. Step 2. Copy and unzip files to./plugins/redmine_contacts_invoices/ 1. To login to your remote machine type in the terminal: $ ssh your_username@remotehost.com This command will prompt the request to enter your user password. 2. Copy.zip archive to the remote server with the following command: $ scp local_path/redmine_contacts_invoices.zip username@server:/ path_to_redmine/plugins/ 3. Unzip archive by the following command: $ unzip path_to_redmine/plugins/redmine_contacts_invoices.zip 4. Install dependent gems using this command: $ bundle install --without development test If you have troubles with installing gem Rmagick, you can use the following command: $ bundle install --without development test rmagick Rmagick is a Ruby and Rails gem which is not mandatory for the stable operation of Redmine and Invoices plugin. 7

8 5. Migrate the database and copy plugin s assets by the following command: $ bundle exec rake redmine:plugins NAME=redmine_contacts_invoices RAILS_ENV=production 6. Restart server to ensure your changes are recognized by the server. If installation was successful, you should see the plugin in the Administration Plugins (Figure 5). VMware Image In case of any difficulties with your environment or lack of time, you can download VMware Image with preinstalled Ubuntu LTS, Redmine and light versions of our plugins. The image is accessible via Figure 4. Invoices plugin successful installation torrent or our FTP server at a. Upgrade Invoices Before performing any operations connected with upgrading your Invoices plugin, please make sure to fully backup your system (including database). You can upgrade to the latest version (2.2.1) from any version starting from If you want to upgrade from the earlier version (1.1.0) you may want to export your invoices to the new fresh installation of Invoices plugin (using CSV export feature). To perform an upgrade, delete the entire folder redmine_contats_invoices 8

9 $ rm -rf path_to_redmine/plugins/redmine_contacts_invoices Copy and unzip the latest version to the plugins directory and run the bundle command, migrate the database and restart server. 9

10 5. Configuration Invoices global configuration is available in the Administration -> Invoices section (Figure 5). Figure 5. Global Invoices plugin settings (Tab General) In the following section we will discuss each element in the settings form. Invoice number format This option defines the invoice number format. You can supply custom characters along with the macros. 10

11 %%YEARLY_ID%%, %%MONTHLY_ID%%, %%DAILY_ID%% inserts the incremental ID within the respective period (year, month, day). %%ID%% inserts the overall ID in the system %%YEAR%%, %%MONTH%%, %%DAY%% inserts the respective values. Excerpt invoice list If enabled, this option transforms the invoices list to a more stylish way of representation (Figure 6): Figure 6. Excerpt invoice list style The default list is represented in Figure 7. Figure 7. Default invoice list style Show invoices in top menu Defines whether Invoices link is displayed on the top pane (Figure 8). 11

12 Figure 8. Show invoices in the top menu Show expenses in top menu Defines whether Expenses link is displayed in the top pane (Figure 9). Figure 9. Show expenses in the top menu Template This option sets the default invoice template unless other template is specified in the project settings. Lines Grouping If you want to group your entries in automatically generated invoices by default, you may want to specify one of these: By activity By issue By user Single line By time entry All Option All allows you to select which grouping to apply manually each time you generate an Invoice. Disable taxes Option disables tax field in the new invoice form and automatic taxes calculation. Default tax value 12

13 Specify the default tax rate (e.g. 20%). Total including tax If enabled, the Total string will be replaced with Total, including tax in the PDF file of invoice. This option does not affect the calculation procedure. Default currency Select your default currency. Thousands delimiter Select default thousands delimiter. Supported delimiters are space, comma and dot. Decimal separator Select decimal separator: dot or comma. Filter companies If enabled, the client select menu in the New Invoice form will only show companies. Line units This is the units of measure. Please specify our values one per each line (Figure 14). Figure 10. Line units 13

14 6. Invoices Templates a. Classic Classics are always valuable. This is a simple template for those who hold the opinion the simpler the better. This templates does not include a company logo. Figure 11. Classic invoice template 14

15 b. Modern Modern template with thinner lines and company logo. Company billing address is aligned to the left and invoice information is moved down. Figure 12. Modern invoice template 15

16 c. Modern Left Variation of the Modern template with oppositely realigned sections of a company address and invoice info. Figure 13. Modern Left invoice template 16

17 d. Modern with blank header Another variation of modern template with no header and logo. Figure 14. Modern with blank header e. Invoices Templates Customization Currently, there is no support for template customization out of the box and it requires hardcoding. Invoices PDF reports are generated using prawn gem. If you want to customize templates or create new, please check the prawn gem documentation accessible at The file you will need to take into account is located at the path: 17

18 path_to_redmine/plugins/redmine_contacts_invoices/lib/reports/ invoice_reports.rb This file contains several methods like invoice_to_pdf_classic and invoice_to_pdf_modern which are directly responsible for forming layouts. 18

19 7. Create and Manage Invoices To start using Invoices, enable it in the project s Modules settings. In this case Redmine Invoices plugin demo is the title of project. Figure 15. Enable Invoices module for specific project Now you are ready to go. There are two ways for generating an invoice: manual and based on the time spent on various activities. a. Create invoice manually Go to your project (in our case it is Redmine Invoices Plugin Demo ) and click tab Invoices. Remember, Invocies plugin should be enabled for your project in the project s settings. Click New Invoice button (Figure 16). 19

20 Figure 16. New Invoice You will see a new invoice form. Your invoice ID will be pre-generated from your configuration, or you can enter custom value. Add the information needed as it is shown on the picture: connected project, status, client, specify the user responsible for the operation, invoice date, currency, discount and invoice language. By default, invoice language is set to the one, which set in the configuration of user, but you can select the language manually. The second section Invoice lines includes the most important information: description of the service/product, quantity (Qty), units of measure, unit price and tax (it is disabled in Figure 17). Figure 17. New Invoice form 20

21 b. Creating invoice from contacts list page Another way for creating invoices is through contacts module. Navigate to the specific project and open the contacts tab. Do a right click on the contact (employee or company) and select Invoice. This procedure will automatically assign client and project leaving everything else for you to complete. Figure 18. Create new invoice by right click on contact c. Create invoice on the basis of time spent You can bill on the basis of time spent on a particular ticket (issue) or set of issues (Figure 19). For this, you will need to enable Issues tracking in the project s settings. Invoices plugin is also 100% compatible with our plugin Helpdesk, which transforms your Redmine into full-featured client support system. 21

22 Figure 19. Create invoice from issues page Navigate to your project s issues and select one or several issues. To select several issues press and hold Shift key while selecting issues with your mouse left key. Figure 20. Spent time If you want to bill only certain activities within one ticket, you can do this by navigating to the ticket view and clicking on the spent time value (Figure 20). This action will bring you to the time entries page (Figure 21). As with the issues page, hold down Shift key to select multiple entires and do a right click. Click New Invoice and select grouping type. 22

23 Figure 21. Create invoices from time entries page If you did not explicitly set the Grouping option to one of the values in the Invoices administration page (see Figure 5) and left it to be default ( All option), you will be able to manually choose one of the invoices entries grouping option from the list: By activity By issue By user Single line By time entry In our example, we choose By activity option. This would generate the form similar to what you have seen in the Figure 17, except it automatically fills for us issues grouped by activity and quantity (time spent on issues, or log time). Fill the form and your prices for each type of activity and taxes (if applicable) to finish. Click Save and it is done Now you should see the invoice in the list and have the ability download PDF report of the invoice. Figure 22. Automatically generated invoice form (grouped by activity) 23

24 8. Adding Payments for Invoices Let s say your invoice suggests payments by installments, or your client has problems with one-time payment (insufficient liquidity or problems with accounts receivables). How to track payments for such invoices? Luckily, we added the feature to track the payments. Just open the respective invoice and click Add payment button. In the form opened, fill in the Amount paid and Payment date. Optionally, you can add description to clarify the circumstances of payment for other users and attach files. When the sum paid reaches the Total specified in the invoice, the status of the invoice automatically changes to Paid without ability to edit it explicitly. Paid status will change automatically to Send if you delete one or several payments for an invoice, so the paid total is less than invoice total. Other possible statuses are: a. Status a. Explanation Invoice is a rough estimation for discussion with colleagues and clients. The final version of the invoice was sent to the client. The invoice was canceled due to violation of contract, changes in the plan and other reasons. 24

25 9. Expenses Along with invoices you have probably already noticed Expenses section. Expenses enhance the functionality of Invoices, allowing to keep track of the additional non-time based investments during the project. In other words, these are investments into fixed assets. Real world example: You are the organization, which provides software development services for the clients. The main cost in this industry is time, so the client primarily pays the hour rate multiplied by the number of hours needed for development. However, sometimes you may need to buy third-party software or service in order to proceed with development. In this case, Expenses will be handy for you, since you will have ability to keep track of such investments and provide a full breakdown of the costs of third-party solutions in the client s project. Create draft of expenses to evaluate a scope of cost for the client for different solutions and discuss them with you client. Another example: You are a residential repairs company. The client pays for the area (e.g. in squared meters) multiplied by the cost of particular work (tiling, wallpapering, plastering and other types of work). You, as an executor of repairs usually is responsible for the materials purchase. As in the previous example, expenses will help you to keep the track of the cost. 25

26 10. Integration with Finance Plugin Invoices plugin plays nicely with RedmineCRM Finance plugin. This manual does not focus on the Finance plugin itself, but we will discuss relation aspects between two plugins. Finance is a plugin for Redmine for simple accountancy developed for nonaccountants. It allows to keep track of operations, both income and expenses. The sources of the income/expenses could be adjusted for your needs and you may configure it to meet, for example, IFRS basic fundamentals. But, in the meantime, Finances could not be considered as an alternative for serious accountancy packages. Integration between Finance and Invoices lies in the ability for you to create a link between any operation and any particular invoice. This will not change any calculations, or change the balance, and will only help to trace back each operation. Instead of expenses section in Invoices plugin, Finance plugin was conceived as a ledger for internal operations, while expenses are operations connected with external clients projects. a. How to create a link between operation and invoice? Given you have enabled Fincance plugin in your project, you can create a link if you open up your project and proceed to the Finances tab (Figure 23). Figure 23. Link Invoices with Finances plugin 26

27 Click Add button located opposite to Invoices caption and in the revealed form enter the desired invoice number. Click Add once again. The relation was created and you should see the respective relations on the Invoice and Operation show pages. Figure 24. Linked invoice in operation view Figure 25. Linked operation in invoice view 11. CSV Import and Export Pro version of Invoices plugin allows you to import and export expenses and invoices in CSV format. Navigate to your project s Invoices or Expenses tabs and you will see Import button in the top submenu (1) and Also available in CSV link (2) at the bottom. CSV import and export fully supports custom fields,. For import be sure to name your columns exactly as they are named in the Redmine system, or it will cause import error. 12. Roles and Permissions Configuration Figure 26. CSV import/ Export Roles and permissions are used for controlling user permissions for certain user roles within Redmine system. This is handy if you have an extensive number of projects and sub-projects and users controlling them. We added Roles and Permissions support for Invoices plugin. To configure it please navigate to Administration -> Roles and Permissions section. This action will bring you to the screen presented in the Figure

28 Figure 27. Roles and Permissions Screen On the page you can list of al user roles in your system. Click on the role for which you want to manage permissions or create new one. This action will redirect you directly to the form of selected users role permissions. Find Invoices section in this list. The section is represented in the Figure 28. Figure 28. Invoices permissions section for user role Most of the fields are self-explanatory and do not require any further comments. The thing to mention here is that some permissions are dependent from each other. For example, user cannot delete invoice, if he 28

29 doesn t have the ability to see them (Formally he does, in the case of using REST API, but not from user interface). Manage Invoices permission defines whether user has rights to edit project s setting for Invoices. 13. Redmine Services If you need further customization of our plugins and Invoices plugin in particular for your special requirements, but you do not have enough expertise to proceed with plugin development, you may be interested in our Redmine Services, which include Plugin Development, Theme Customization, Extended Support and Maintenance and Installation Services. You can find additional info on our Redmine Services web-page: redminecrm.com/pages/services. 14. Language Support RedmineCRM Invoices plugin officially supports English language. All other languages were contributed by the community and are supplied as is. Currently supported languages: English, Danish, German, French, Hungarian, Japanese, Korean, Polish, Brazilian Portuguese, Russian, Swedish. We will be very grateful if you provide translation for your language or edit existing translations to include in future bundles. 15. Terms and Conditions You should carefully read the following terms and conditions. Your purchase or use of our products indicate that you have read and accepted these terms and conditions. 1. RedmineCRM grants you a nonexclusive limited license to use the products you acquire through our web site in accordance with these Terms and Conditions (the "license") issued by our company. 2. All our extensions are released under the GPL v2 license. For more information please read our License Section. 3. You may make any changes to the code, however we don't support extensions with modified code. 29

30 4. Our code isn't encrypted. You are authorized to make any necessary modification(s) to our products to fit your purposes. But may not change or remove the copyright information. 5. You may not sub-license, assign, or transfer this license to anyone else without prior written consent from RedmineCRM 6. You may not claim intellectual or exclusive ownership to any of our products, modified or unmodified. All products are property of RedmineCRM 7. Our products are provided "as is" without warranty of any kind, either expressed or implied. In no event shall our juridical person be liable for any damages including, but not limited to, direct, indirect, special, incidental or consequential damages or other losses arising out of the use of or inability to use our products. 8. Upgrades are free for one year since purchase date. Our products are always designed for the latest stable version of Redmine, but we can give no guarantee, that the products will run with future versions of Redmine. You may use our support system or to address any issues related to software versions and updates. 9. Once you make the payment, you will be able to download the product on the "License Manager". 10. We are not warranty or guarantee our products in any manner. We cannot guarantee they will function with all 3rd party components, as there is currently no certification process for such components. 11. RedmineCRM reserves the right to change or modify these terms with no prior notice. 16. Licensing RedmineCRM Licencing This End User License Agreement is a binding legal agreement between you and RedmineCRM. Purchase, installation or use of RedmineCRM Extensions provided on redminecrm.com signifies that you have read, understood, and agreed to be bound by the terms outlined below. RedmineCRM GPL Licencing All Redmine Extensions produced by RedmineCRM, Inc. are released under the GNU General Public License, version 2 ( gpl-2.0.html). Specifically, the Ruby code portions are distributed under the GPL License. If not otherwise stated, all images, manuals, cascading style sheets, and included JavaScript are NOT GPL, and are released under the RedmineCRM Proprietary Use License v1.0 (See below) unless specifically 30

31 authorized by RedmineCRM. Elements of the extensions released under this proprietary license may not be redistributed or repackaged for use other than those allowed by the Terms of Service. RedmineCRM Proprietary Use License (v1.0) The RedmineCRM Proprietary Use License covers any images, cascading stylesheets, manuals and JavaScript files in any extensions produced and/or distributed by redminecrm.com. These files are copyrighted by redminecrm.com (RedmineCRM) and cannot be redistributed in any form without prior consent from redminecrm.com (RedmineCRM). Usage Terms You are allowed to use the Extensions on one or many "production" domains, depending on the type of your license. You are allowed to make any changes to the code, however modified code will not be supported by us. Modification Of Extensions Produced By RedmineCRM. You are authorized to make any modification(s) to RedmineCRM extension Ruby code. However, if you change any Ruby code and it breaks functionality, support may not be available to you. In accordance with the RedmineCRM Proprietary Use License v1.0, you may not release any proprietary files (modified or otherwise) under the GPL license. The terms of this license and the GPL v2 prohibit the removal of the copyright information from any file. Please contact us if you have any requirements that are not covered by these terms. 31