# Plugin SubscriptionS

## About

The plugin provides the following functionality:

- storing information about customer product subscriptions;

- subscription price calculation;

- generation license file for sending it to customers;

- reporting about money distribution over product owners.

Using the plugin implemented the BGERP Development Support System, allowing us to drive our product further.

## Setup

| You can see (queues Plugin Subscription Product and Plugin Subscription Subscription) the plugin operation in Demo System.

### Process Types

In configuration participate the following process types.

#### Product

Represents information about product, available by subscription. Has the following parameters:

- Product ID - unique text product identifier, used for license generation and calculation of price;

- Price - one ore more listcount prices, value IDs must be the same as in Limit parameter of subscription.

#### Subscription

Contains information about customer’s subscription, parameters:

- Email - email customer with the subscription’s customer;

- Subscription - list with values equals to configured subscription’s IDs;

- Limit - list with values of allowed subscription limit, e.g. number of concurrent connections;

- Service Cost - money with value of Consultant' reward over of product prices;

- Discount - money with an optional discount;

- Cost - read-only money with month price, calculated as Products Costs for the Limit + Service Cost - Discount;

- Date To - date end of license, placed in license file;

- License - read-only file with generated license file, updated automatically on changing Date To.

Add Invoices tab in the type properties configuration.

### Configuration

Make sure the plugin is enabled in configuration.

Add in the plugin configuration the following block:

    subscription:sign.key.file=<privateSshKeyPath>

    # product process params
    subscription:param.productId=<paramProductId>
    # subscription process params
    subscription:param.email=<paramEmailId>
    subscription:param.subscription=<paramSubscriptionId>
    subscription:param.limit=<paramLimitId>
    subscription:param.cost.service=<paramServiceCostId>
    subscription:param.cost.discount=<paramDiscountId>
    subscription:param.cost=<paramCostId>
    subscription:param.dateTo=<paramDateToId>
    subscription:param.lic=<paramLicId>
    # optional user params
    #subscription:param.user.incoming.tax.percent=<paramIncomingTaxPercentId>
    # optional keys
    #subscription:max.dateTo.months=<maxDateToMonths>

Where:

- <privateSshKeyPath> - file path with private SSH key, used for signing license files, for example: /home/bitel/.ssh/id_rsa, the public key has to be introduced in key using App;

- <paramProductId> - ID of Product ID parameter;

- <paramEmailId> - ID of Email parameter;

- <paramSubscriptionId> - ID of Subscription parameter;

- <paramLimitId> - ID of Limit parameter;

- <paramServiceCostId> - ID of Service Cost parameter;

- <paramDiscountId> - ID of Discount parameter;

- <paramCostId> - ID of Cost parameter;

- <paramDateToId> - ID of Date To parameter;

- <paramLicId> - ID of License parameter;

- <paramIncomingTaxPercentId> - ID of user parameter of type text with incoming payments tax, taken on account in Payments Report;

- <maxDateToMonths> - how many months in future from the current one can be set Date To parameter value.

#### Subscriptions

Add the following configuration block for each of supported subscriptions.

    subscription:subscription.<ID>.title=<TITLE>
    subscription:subscription.<ID>.process.type=<processSubscriptionTypeId>
    subscription:subscription.<ID>.param.limit.price=<paramLimitPriceId>

Where:

- <ID> - unique numeric subscription ID;

- <TITLE> - subscription title;

- <paramLimitPriceId> - ID of Price parameter.

##### Paid Invoice Actions

The plugin supports several actions on paid invoices in a subscription process. To activate them in a subscription configuration should be added the following keys.

    subscription:subscription.<ID>.paid.invoice.dateTo.expression=<dateToExpression>
    # optionally
    #subscription:subscription.<ID>.paid.invoice.email.message.type=<emailMessageTypeId>
    #subscription:subscription.<ID>.paid.invoice.email.subject=<emailSubject>
    #subscription:subscription.<ID>.paid.invoice.email.text.expression=<emailTextExpression>

Where:

- <dateToExpression> - JEXL expression for calculating a new license Date To value, with additional context variables:

  - invoice object of org.bgerp.plugin.bil.invoice.model.Invoice

- <emailMessageTypeId> - message type ID of type Email which will be used for creation of a notification mail with a new license file, exact ID value may be replaced to 0 that will take the first message type of type Email from server configuration;

- <emailSubject> - the mail’s subject;

- <emailTextExpression> - JEXL expression for generation the mail’s content, with additional context variables:

  - invoice object of org.bgerp.plugin.bil.invoice.model.Invoice

Here a sample of subscription configuration taken from Demo.

    // PzdcDoc snippet of: 'Plugin Subscription subscription config', lines: 20 - 28

    subscription:subscription.2.title=BGERP EUR
    subscription:subscription.2.process.type={@PROCESS_SUBSCRIPTION_TYPE_ID}
    subscription:subscription.2.param.limit.price={@PARAM_LIMIT_PRICE_EUR_ID}
    subscription:subscription.2.paid.invoice.dateTo.expression=tc.toLocalDate(invoice.getDateTo()).plusDays(1).plusMonths(1).plusDays(20)
    subscription:subscription.2.paid.invoice.email.message.type=0
    subscription:subscription.2.paid.invoice.email.subject=BGERP License
    subscription:subscription.2.paid.invoice.email.text.expression=<<END
        "Dear Customer," + NEW_LINE2 + "as an attachment you will find the prolonged license."
    END

### Price Calculator

The price calculator is implemented as an open process queue with processor. The queue has to be assigned to Product process type, and have following processor in configuration:

    processor.{@inc:cnt}.iface=open
    processor.{@cnt}.page.url=/open/plugin/subscription/subscription.do
    # optionally predefined subscription value
    #processor.{@cnt}.subscription.value=<ID>

Where:

- <ID> - unique numeric subscription ID.

## Usage

### Product

Product Owner is a user, becoming profit from subscriptions, using his product, has to be assigned as an process executor with role=1.

### Subscription

Each customer subscription is presented as a process with related Product processes with type Depend.

An Consultant is a user, taking responsibility for the process and becoming profit in size of Service Cost parameter value. The Consultant has to be assigned as a process executor with role=0.

Subscription Cost parameter value is automatically recalculated on changing subscription, limit, related products, discount or service cost parameters.

After sending an invoice and paying that, Date To parameter has to be changed, that update License File.

### Reports

Using the reports each payment receiver can determinate parts of Consultants and Owners.

Subscription Payments Report shows how much money owns a report generating payment receiver to plugin Owners and Consultants.

Subscription Debts does the opposite, show how much an Owner or Consultant should receive.

### Price Calculator

In open process queue customers can choose interesting subscription, products and limit and get subscription month price.