Expired Subscriptions

You can find users who have expired subscriptions by using the 'Subscribers' entry in the Admin menu.

This allows you to select users who have one role, but not another.

By default it is set to display users who have the role Subscribed but not the role Subscriber. However, you can use it to users who have any role but not another.

If you set the 'Not' role to <Any> then  the 'not' condition is ignored.

Expiry Dates

There are two dates that are used to drive our subscription system:

The Subscription Date - this is the date the subscription was first purchased. For old subscribers it needs to be set manually. For subscribers who purchase their first subscription through the system, it is set automatically when they do so.

The Subscription date is passed to the Keygen utility and it uses this and the current date to figure out when the subscription key should expire.  The day and month can be got from the Subscription date, but the year has to be calculated. Provided that the current date (ie the day on which the payment for the subscription renewal is received) is between two months prior to the subscription anniversary, and 10 months after, then the key expiry date will be calculated correctly.

The same process occurs when the zero cost 'Subscription Key' product is "purchased" - ie the generated key will have an expiry date derived from the Subscription Date and the current date.

The Subscriber Role Expiry Date - we use this to send out a reminder 1 month prior to the subscription's expiry. 'Role expiry' is a feature of the standard Ubercart e-commerce system that we use.  When the customer purchases an Annual Subscription, then if they do not currently have this Subscriber role (either because this is their first subscription purchase, or because the role expired) they are given the role and it is set to expire in 12 months.  It they do have the role, then 12 months is added to its expiry date.

Note that when the zero cost 'Subscription Key' product is "purchased" it does NOT affect the Subscriber role.

The Role Expiry Date is set to the anniversary of the Subscription Date.  This is achieved by modifying the standard role expiry code to add an expiry type of 'Subscription date', and having code that recognises this expiry type and sets the appropriate date.

This implies that the Annual Subscription product - see http://www.openvpms.org/node/656/edit/features - MUST have its features set as follows:

and the Global expiration - see http://www.openvpms.org/admin/store/settings/products/edit/features - must be as follows:

Finding users

If you need to access a specific user, you can call them up via http://www.openvpms.org/users/xxx where xxx is the user's login name.

However, it may be easier to find then via http://www.openvpms.org/admin/user/user/list (or via User Management|users|List in the top menu)

Initially this shows everybody as follows:

But you can list by role – ie if you click the role radio button and select Subscriber from the pull-down and then press Filter you get:

On this screen, you can add a second selection condition (say Role = FiftyPercenter) and then press the Refine button, you will see only users who are Subscribers and FiftyPercenters.  Pressing the Reset button removes all the selection conditions.

Note that the Role Expiration tab show when user’s roles expire – as below.  Note that this shows ALL expiring roles, not just those of the users that you have selected on the List tab.

You can click on any on the Username links to call up that user.

Generating a subscription key

In the normal case, a user buys an Annual Subscription and the system automatically generates and emails their subscription key when their payment is received (ie immediately for PayPal payments or when the order is marked as payment-received by the store manager).

However, it may be necessary to generate a key separately.

To do this the store manager generates a order for the user for the product 'Subscription Key'.  This is a zero cost product.

The process is as follows:

Use Store Administration|Orders|Create Order (ie http://www.openvpms.org/admin/store/orders/create) which will display:

Use the 'Search for an existing customer' link to select the customer (or if necessary create a new customer), and then click the 'Create order' button.

This will display:

Use the 'Select from address book' button to select the customer's address. The fields that we need and the first and last names and the Practice Name - the rest do not matter in this case.  We also do not need the ABN number.

Further down the screen:

Select the payment method 'Free order', then press the Add product button, click on 'Subscription Key' and then press the Select button.

This will give:

Click the 'Add to order' button which will give:

If you want you can click on the 'Add an admin comment' link to add one, else click the 'Submit changes' button.

This will give:

Now click the View tab to get:

Down the bottom change the Order status from 'Pending' to 'Payment received' and click the Update button.

This will give:

The process is now complete and the subscriber will receive their key via email.

Manage Orders

Orders paid via PayPal will 'auto-complete' on successful return from PayPal, and the user's subscription status will be updated and their subscription key emailed to them.

However, orders paid by cheque or bank transfer need to be updated from Pending to Payment Received status when the money has been received. This will trigger the update of the user's subscription status and will email their subscription key, and set the payment status to Complete.

This is most easily done via http://www.openvpms.org/admin/store/orders (or using Store administration|Orders|View orders in the top menu).

This will show a display like the following:

By default, the 'Active Orders' are shown. You can also select Pending and other states.

To process a Pending order, click the left-most icon in the Actions column (view order).  You will see something like:

You can click the Receive Cheque link (at the top right) to indicate that the cheque has been received.  This will result in the following screen:

Assuming that you do not want to add a comment, and that the cheque was for the full value, you can simply click the Receive cheque button at the bottom.

This will set the order status to Completed and return you to the order view screen as shown below:

If the payment method was bank transfer rather than cheque, then the process is exactly the same.

Note that if you now check the 'Send e-mail notification..' box and then press the Update button, an email will be sent to the user saying that their order is now complete.

You can then click the Orders part of the breadcrumb at the top of the screen to return you to the orders listing.

Manually set Initial Subscription date

To manually set the Initial Subscription date, you need to edit the user's profile.

You do this via http://www.openvpms.org/users/xxxx where xxxx is the user's login name.  However, you may not know this.

The easiest way is to use the Who Bought What report to display the subscription purchases, and then click on the user's name. Note that if you click on the Email column heading, it will sort by email address and hopefully, all the subscription purchases by the one practive will be grouped together.

Clicking on the user's name will bring up the user screen as follows:

Click the Edit tab and then the Subscription Information sub-tab to bring up the following:

If the Initial Subscription date has never been set it will show today's date.  Set the date as appropriate and then click the Save button.

Orders in Checkout status

Occasionally, users may have an order that they have entered, but not submitted.

This leaves the order with status 'In Checkout'. You can find these on the Orders screen (Store Administration|Orders|View Orders - http://www.openvpms.org/admin/store/orders/view ) by setting the status selection to In Checkout.  Note that the default 'Active Orders' selection does NOT include 'In Checkout' orders.

For these orders, you need to do one of three things:

if you have received the money, then you need to use the Received payment link on the order (just as you do when you receive the money for an order in Pending status).

If you have not received the money and this is a recent order, then you need to email the user and ask what is going on.  They will be able to examine the order using the My Cart link or by going to http://www.openvpms.org/cart

If the user does not want to proceed, then you can simply view the order and change its status to Cancelled and add a suitable Admin comment.

NOTE: Before you email the user, check that there is not another order for the same item(s) with the same date that has been Completed (or is Pending). In this case we have a duplicate and we can set the status of the 'In Checkout' order to Cancelled with an Admin comment like 'Cancelled by PG - duplicate of completd order'

Price changes

If/when the subscription amount changes the following pages need updating:

http://www.openvpms.org/yearly-openvpms-subscription-1-fte-vet

http://www.openvpms.org/admin/store/uc_discounts/list

Note that the discount needs to be set so that the subscription component is discounted by 50%, but not the development levy.  ie if the total T = S + L (where S is the subscription and L the devlopment levy) then the discount is (S/2)/T

http://www.openvpms.org/admin/store/ca/uc_role_notify_grant/edit/actions
http://www.openvpms.org/admin/store/ca/uc_role_notify_renew/edit/actions
(In both the above change Dev.levy amount in email text)

http://www.openvpms.org/subscription

Set FiftyPercenter and Subscriber roles

The store manager needs to set the role FiftyPercenter for those users who should have it.

See also http://www.openvpms.org/openvpms-site-administration/store-ubercart/roles

Note that the store manager role explicitly has permission to set/unset the FiftyPercenter and Subscriber roles for any user.

To set/unset the FiftyPercenter role, access the user - see Finding Users - then edit the user and set/unset the role as desired. See  for example below.

Note that if you do set the Subscriber role (which is normally automatically set as the result of the user purchasing a subscription), then you will also need to set the Initial Subscription Date (accessed via the 'Subscription Information' tab), and the Subscriber role expiry date (accessed via the Ubercart roles block right at the bottom of the Account tab page).

Who Bought What

The Who Bought What report (accessed via Store administration|Reports|Who Bought What or http://www.openvpms.org/admin/store/reports/uc_who_bought_what ) is very useful.

You can select the products to be reported as follows:

Note that the 'Subscription Key' product will show the $0 orders created just to generate keys for customers, and thus provides a track of the cases where the key was sent out independently of the customer's purchase of an Annual Subscription.

The Development Project Donation shows donations to projects and can be used to track both payments and pledges (which will be shown with HowPay as 'other').

Other modules

The standard functionality of Ubercart is extended using the following modules: 

Roles

The 'roles' facility is important to the complete Drupal system in that it is used to control who does what.

As far as the Ubercart module is concerned, three things are important:

1. For a person to control the Store module, they need to be given the role 'shop manager'
2. We use Ubercart's ability to assign a role to the user who purchases a product to assist in the administration of OpenVPMS Subscriptions
3. We use the Ubercart Alt Discount module's ability to set a discount if the user has a specific role

Thus, we have created the role 'Subscriber' (via http://www.openvpms.org/admin/user/roles ) which is assigned to the user when they purchase their subscription, is set to expire in 1 year, and has an 'expiry warning' time of 1 month (set via http://www.openvpms.org/admin/store/settings/products/edit/features ).

We have also created the role 'Subscribed'. This is also assigned to subscription purchasers, but never expires. Hence we can find users whose subscriptions have lapsed by looking for users with the role Subscribed but not Subscriber. [This is done using the View and Update Users screen - http://www.openvpms.org/admin/userlist ]

There is also the role Subscriber-Ex. This is used to flag ex-subscribers. No user should have the roles Subscribed and Subscriber-Ex at the same time. There is no programmed block against this, it is just illogical to do so.  Any user who used to be a subscriber, but no longer is (either because they are no longer an OpenVPMS user, if their practice's subscription is held under another name) should have their role Subscribed removed and Subscriber-Ex added. This is done manually by editing the user.

We have also created the following roles:

'FiftyPercenter':  This is manually assigned by the shop manager to any users who were early supporters of OpenVPMS and who are entitled to a 50% discount on their $300 subscription but pay the $150 development levy via the 'Early OpenVPMS Supporter' discount of 33.3333%. The store manager assigns the role via http://www.openvpms.org/users/xxxx (where xxxx is the user's login name) to access the user's profile and then editing this to set the role FiftyPercenter.

'Not For Profit (with clinic)': This is manually assigned to any organisation that is a) not for profit; b) runs a vet clinic open to all. This role gets the 'Not for profit clinic' discount of 33.3333%

'Not For Profit (no clinic)': This is manually assigned to any organisation that is a) not for profit; b) does not run a vet clinic open to outsiders. This role gets the 'Zero Cost' 100% discount.

'Developer': This is manually assigned to any person who is doing development amed at improving/expanding OpenVPMS. This role also gets the 'Zero Cost' 100% discount.

Note that via the role_delegation module, the store manager is explicitly given permission to set/unset the Subscriber, Subscribed, Subscriber-Ex and FiftyPercenter roles for any user.

If you do need to manually set the Subscriber role for some reason, do NOT just tick the Subscriber role, but rather, down the bottom of the page in the Ubercart roles section, add the Subscriber role with the appropriate expiry date.

Subscription date

In order to support subscription automation we need to keep a 'subscription date' in the the system.  In fact we keep the Initial Subscription date.  This has been done by adding an 'Initial Subscription' field to the user's profile (via http://www.openvpms.org/admin/user/profile ). Note that this field is hidden from the user and ie either set manually by a 'store manager' or by the system when the user first buys a subscription. This field is declared as a date and is actually held by as an array containing the day, month and year. 

We need the Initial Subscription date so that we can correctly set the expiry date, not to 12 months after the user purchases the subscription renewal, but rather to the anniversary of their initial purchase.

This is implemented by the 'Run Keygen' condition action code which sets the Subscription Date to the current date if it has not been previously set.  Note that since this code is run when payment is received, the Subscription Date is set to the date on which payment was received for the first subscription - and not the date on which the order was placed.

The code can be found at http://www.openvpms.org/admin/store/ca/2/edit/actions

Tailoring

This section records the tailoring done - so that things can be adjusted in the future if necessary. [Note that not everything is noted here - just the parts that are more difficult to find - mostly those parts that are not accessible via the top menu.]

Order Templates

The standard Ubercart order templates are held in
  /home/admin/www/sites/all/modules/ubercart/uc_order/templates

These are overidden by having modified versions in
  /home/admin/www/sites/all/themes/openv

The three files are:
  uc_order-admin.tpl.php
  uc_order-customer.tpl.php
  uc_order.tpl.php

Checks to Cheques

In the cheque payment module, the phrase "Checks should be made out to" is hard coded in the file /home/admin/www/sites/all/modules/ubercart/payment/uc_payment_pack/uc_payment_pack.module

Although there are mechanisms in Drupal to translate this, it was considered far simpler to just edit the file to change this to "Cheques should ....".

Role Expiry Date Format

In the ubercart roles module, in the file /home/admin/www/sites/all/modules/ubercart/uc_roles/uc_roles.module, and extra date format has been added to provide a d MMM YYYY date format. The modification signature is "TG 28/05/2015".

This format is used in the role expiry emails. (The standard 'small' format includes the time and this is not wanted.)

Role Expiry Type

In the same file (uc_roles.module) a 'Subscription date' (code 'sub') has been added. The modification signature is "TG 25/6/2015".

Role Expiry Date

In the same module, the file uc_roles.ca.inc, has been modified to calculate the role expiry date from the Subscription Date - provided that the Role Exiry Type is 'sub'. The modification signature is "TG 25/6/2015".

The logic used is the same as that in the keygen utility.  This ensures that the the Subscriber role has the same expiry date as the generated key.

Collapse discounts pane

By default, the discounts pane in the checkout window is shown uncollapsed as follows:

Since we do not use discount codes, and since the above may confuse users, the code has been modified to initially display the pane in its collapsed state as follows:

Note that testing has shown that if this pane is totally suppressed, then if there is a FiftyPercenter discount applicable, the amount calculations are wrong.

The only way to set this pane as initially collapsed is to modify the file /home/admin/www/sites/all/modules/uc_discounts_alt/uc_discounts/uc_discounts.module to add the following at the end of the uc_discounts_form_uc_cart_checkout_form_alter function:

/**
 * The following added by Tim G to set the uc_discounts pane to initially collapsed
 * suppressing the pane completely screws the discount calculation
 */
  $form['panes']['uc_discounts']['#collapsed'] = TRUE;

Who bought what

This module enables you to list all the purchases of a given product. You can sort the results by clicking on the appropriate column heading.  You can also export the data to a CSV file, either page at a time, or (by clicking the 'Show all records' link at the bottom) all records.

It is accessed either via the top menu via Store administration|Reports|Who Bought What or directly via http://www.openvpms.org/admin/store/reports/uc_who_bought_what

Note that the CSV file contains more data than is displayed on the screen.  In particular it shows the 'billing_company' (in column Z) - this should contain the name of the practice.

Debugging

If you are debugging php code (either in the 'execute php code' of conditional actions, or in modified modules) then the devel module is invaluable.

Install using 'drush dl devel' then 'drush en devel' (you only need to enable this module and not the other two in the download).

Then set the Devel module permissions for the administrator user only (via http://test.openvpms.org/admin/by-module - you are working in the test system aren't you).

We do not have this module installed in production so it needs to be installed on the test system after test is cloned from production.

Where you want debug output, use the dpm() call - eg as follows:

and the output appears in the message portion of the screen as follows:

NOTE - the dpm() calls cause errors if the devel module is not installed.  Hence these have to be removed from the code before moving it to production.

Advanced Poll

The javascript code in /home/admin/public_html/openvpms.org/public/sites/all/modules/advpoll/advpoll-vote.js has one line commented out so as to allow the use of links in poll choices - as follows:

CKEditor profiles

The CKEditor profiles - see http://www.openvpms.org/admin/settings/ckeditor - have been adjusted.

The profiles are set as:

The Advanced profile is adjusted so that:

1. The Advanced Content Filter is disabled so that tags are not filtered
2. The HTML filter is disabled.  

The global profile role precedence is:

Visibility settings are:

The simplified toolbar is set as follows:

Download page

The page www.openvpms.org/download has some javascript embedding.  To see this edit the page and switch to Source mode - this will show:

When you update this page for a new release, you also need to update the sites/all/js/downloadDialog.js - which is as follows:

You need to edit this to point at the new release.

Modified Outline Designer module

We use a modified version of the the Outline Designer module. The modification enables the copying of books to preserve relative URL references - required when we need to clone the CSH text for the next OpenVPMS release.

See also https://openvpms.atlassian.net/browse/STPA-27

Need to add more here to document the mods.

Mollom

The Mollom module (which provides spam blocking facilities) needs a subscription.

This is provided by Matt Young - the subscription provides for 3 domains and he only uses 2 and has allowed openvpms.org as the third.

Contact Matt for any Mollom related questions.

Subscription form

This note is here because it is not immediately obvious how the subscription arithmetic is done.

If you edit the subscription form page you see:

If you click the 'Switch to plain text editor' you see:

The added javascript is used to do the validation and calculation.

Cloning the test system

If you wish to re-clone the test system from the production system you should do as follows: (remember to delete any old test-old.openvpms.org first - see below)

Login as admin
cd public_html
mv test.openvpms.org test-old.openvpms.org
mkdir test.openvpms.org
rsync -a --exclude '.git*' openvpms.org/* test.openvpms.org
[this will fail to copy some log files because of permission problems but these do not matter
and we are using rsync rather than cp so that we can exclude the git stuff]
cd ~/wwwtest/sites/default
cp ~/public_html/test-old.openvpms.org/public/sites/default/settings.php settings.php
drush sql-sync @live @test

What the above does is rename the test system to test-old, the copy the production system files to the new test system, and then ovewrite the new test systems settings.php from the old test system (which sets the required database name and site url).  Finally we copy the production database using the drush sql-sync command.

You now need to login to the test system set the Reroute Mail options.

When you are happy you can delete the old test system saved in test-old.openvpms.org using:

sudo rm -rf test-old.openvpms.org

Devel module

If you need to, you may want to install the devel module - see https://www.drupal.org/project/devel and https://api.drupal.org/api/devel/devel.module/6

We do not have this installed on production so it is not simply a matter of enabling it - it needs to be installed on the test system - and you will need to do this again if you re-clone test from production.

Mail re-routing

On the test system we enable the Reroute Email module. This is installed on production but not enabled.

To enable the mail re-routing use Site Configuration|Reroute Email|Settings or http://test.openvpms.org/admin/settings/reroute_email/settings

Set like the following:

You MUST enable rerouting - so notification and other emails are not sent out to users.  You SHOULD change the email address from its default of admin[at]openvpms[dot]org so that only the you (ie the person doing the testing) gets the re-routed emails.

keygen installation

The following is a copy of the keygen readme.txt.

On a linux server, keygen should be installed in /usr/local/bin/keygen
It needs to be here because the php code in the ubercart conditional action custom php code
for the 'Run Keygen' predicate contains the line:
 exec("cd /usr/local/bin/keygen/bin && ./keygen.sh ".$eargs, $output, $return);

Having installed it (by simply creating the /usr/local/bin/keygen directory and unzipping
the contents of keygen.zip into it) you can then do:

 cd /usr/local/bin/keygen/bin
 chmod 755 *.sh               [to set the scripts as executable]
 
then  
 ./keygen.sh --help

to see what to do.

You should then use the --server option to set the various SMTP parameters (see --help output).

This will create ~/.openvpms/keygen.properties

This then must be moved to the appropriate directory - it was created in your home directory - but
we need to put it the home directory of the user who is running apache - who is www-data - and
his home is /var/www

So we need to cd to /var/www and then mkdir .openvpms and copy keygen.properties into this and then
adjust the ownerships to www-data:www-data

If you need to play with keygen on a windows machine, you can unzip the package to any convenient
folder and then cd to its bin folder and then use keygen.bat