====== Summary ======

This page describes the abstract, the concrete client, and the DB model used for the key system. This page does not describe the generic program flow and operations required to implement all features. It may describe certain operations particularly where SQL queries are needed to perform operations. 

====== Abstract License Model ======
The license key system is composed of two major entities and one log (audit) entity. 
  * License Key
  * License User Association
  * License Log Table

The **License** entity is a single item representing the abstraction of a license. It has the following properties:
  * An id, globally identifying the license instance
  * A type identifier indicating what type of key it is.
  * An associated customer, restricting users who may use the key
  * A starttime indicating when the "clock" for this key begins ticking. For permanent and timed licenses the value is computed when the license is created. For Demo and Rental keys, the value is calculated upon initial checkout. 
  * A duration indicating how long the key is good for
  * An expiration date, after which the key is no longer valid. For permanent and timed licenses the value is computed when the license is created. For Demo and Rental keys, the value is calculated upon initial checkout.
  * A product (feature) list of allowable features associated with the license.

Key codes are:
  * P - Permanent
  * S - Software
  * O - One time
  * R - Rental
  * T - Training

Product feature codes are 4 character tuples for each program/feature. Examples might include something like:
  * EW3D - Earthworks 3D
  * EW4D - Earthworks 4D
  * SDAd - SmartDirt Android
  * Accs - Agtek Access Client program.
Note that the code need not represent a user readable string. User's must never be presented with the codes directly but rather specific user readable strings that are understandable to them. It is outside the scope of this implementation to provide meaningful user interface strings, and as such the application programmer is responsible for displaying appropriate strings. While a reasonable US English list of strings may exist, these are not suitable for localized versions of the software.

The **License Association** entity relates a use to the License instance. The associations are limited by business logic (Java server code) to a maximum of 10 associations per license.
  * An id, globally identifying the license association.
  * A keyid, uniquely identifying the license being associated with.
  * A userid, uniquely identifying the user being associated with the specified key.

The **License Log** provides an audit trail of operations and interactions in the license system.
  * An id, globally identifying the log entry
  * Keyid of the license associated with the operation
  * Type code indicating the type of operation being logged.
  * UserId indicating which user invoked this operation
  * Comment free-form text for the operation, might be user entered note. 

Log types are:
  * 'C' - License creation
  * 'I' - License checkin
  * 'O' - License checkout
  * 'E' - Admin edit of key
  * 'U' - Add or remove user
  * 'R' - Rental activation
  * 'D' - Demo activation

===== License Key Timers =====
Variant of Timed Key
| **Key Type** |Start time|Expire time|Expire Updates|Timed expire|Max checkout duration|Note|
|Timed Key     |Set@Key create|create+35d|N/A|Set by AGTEK|Customer settable|
|Permanent Key |Set@Key create|Never|N/A|Set by AGTEK|Customer settable|
|Training Key  |Set@Key create|create+10 days|AGTEK manual op|N/A|Customer settable|Allows all users="*"|
|Rental Key    |Set@Key create|create+1 year|AGTEK manual op|N/A|Customer settable|Called out for billing|

Strange keys
| **Key Type** |Start time|Expire time|Expire Updates|Timed expire|Max checkout duration|Note|
|Software Key  |Set@Key create|create+1yr|now+1 year on renew|Set by AGTEK|N/A|requires periodic renewal()+secret sauce collected and checked on client to server, NEVER allow checkin|
|One Time Key  |Set@Key create|Never|N/A|N/A|Forever|NEVER allow checking or renew|

====== Data Base Tables ======

**License Table**
| **Field** | **Type**     | **Null** | **Key** | **Default** | **Extra** | **Comment** |**mod access**|
| handle    | int(32)      | NO   | PRI | NULL    | auto_increment | Universal ID for key |AUTO|
| type      | char(1)      | NO   |     | NULL    |                | {'T', 'P', 'R', 'D'} |AGTEK|
| custid    | int(16)      | NO   |     | NULL    |                | ID of customer |AGTEK|
| numusers  | int(16)      | NO   |     | NULL    |                | Number of allowed users |AGTEK|
| maxcheckout| int(32)     | NO   |     | NULL    |                | Unix delta time for maximum checkout by user |CUST|
| starttime | int(32)      | NO   |     | NULL    |                | Unix time of key activation |AUTO|
| expiretime| int(32)      | NO   |     | NULL    |                | Unix time for key expire, -1 == never; rental = duration + starttime|AGTEK|
| products  | varchar(255) | YES  |     | NULL    |                | Quad code, comma sep, up to 50 |AGTEK|
| timedproducts | varchar(255) | YES  |     | NULL    |                | Quad code, comma sep, up to 50 |AGTEK|
| timedexpire   | int(32)      | NO   |     | NULL    |                | Expire time for all temporary products |AGTEK|
| checkedout   | tinyint(1)   | NO   |     | NULL    |                | 1 if checked out, 0 if available |AUTO|
| expired      | tinyint(1)   | NO   |     | NULL    |                | 1 if expired, 0 if available |AUTO|

**Operations**
  * Get a list of keys for this user and feature XYZW, select from l license,lu licenseuser where l.custid=## and l.handle = lu.keyid and lu.userid = ##
  * Get a list of keys for this customer, select from license where custid = ##
  * Delete key
  * Add key
  * Update key (different for diff ops?)


**License Users**
| **Field** | **Type**     | **Null** | **Key** | **Default** | **Extra** | **Comment** |**mod access**|
| handle | int(16) | NO   | PRI | NULL    | auto_increment | Universal ID for this association |AUTO|
| keyid  | int(32) | YES  |     | NULL    |                | ID of key to associate |AUTO (driven by admin request)|
| userid | int(16) | YES  |     | NULL    |                | ID of user to associate |AUTO (driven by admin request)|

  * Get list of all users on specific key
  * Delete user association
  * Add user association

**License Log**
| **Field** | **Type**     | **Null** | **Key** | **Default** | **Extra** | **Comment** |**mod access**|
| handle  | int(32)      | NO   | PRI | NULL    | auto_increment | Universal ID for this log entry |AUTO|
| time    | int(32)      | NO   |     | NULL    |                | Unix time of the log |AUTO|
| keyid   | int(32)      | YES  |     | NULL    |                | KeyID assoc with this log. |AUTO|
| type    | char(1)      | NO   |     | NULL    |                | Entry type (see below) |AUTO|
| userid  | int(16)      | NO   |     | NULL    |                | UserID performing op |AUTO|
| comment | varchar(512) | YES  |     | NULL    |                | Free form text |AUTO|

  * List all events
  * List all events of type
  * List all events with key #
  * List all events with custid
  * Add event of type, datetime, user, etc. 
  * Delete events older than date
  * List events older than date (range)

**MOTD** (announcements)

| **Field** | **Type**     | **Null** | **Key** | **Default** | **Extra** | **Comment** |**mod access**|
| handle   | int(32)       | NO   | PRI | NULL    | auto_increment | Unique id of announcement |AUTO|
| products | varchar(255)  | YES  |     | NULL    |                | Product codes affected, null == all products |AUTO|
| expire   | int(32)       | NO   |     | NULL    |                | When this message is no longer active |AUTO|
| message  | varchar(1024) | YES  |     | NULL    |                | Text of message |AUTO|

**Alterations to Customer**
| **Field** | **Type**     | **Null** | **Key** | **Default** | **Extra** | **Comment** |**mod access**|
| hasccess | tinyint(4)       | NO   |     | 0   |  | Indicates if users belonging to this customer can use AGTEK Access |AGTEK|
| haslicense | tinyint(4)     | NO   |     | 0   |  | Indicates if users belonging to this customer can use AGTEK License Server |AGTEK|