License Client Configuration
Client-only Tenant Configuration
First included in DC4CRM 1.6, the License Client is a component that allows dividing your Volumes between tenants. This means setting a limit for each tenant (i.e. the number of concurrent agent logins for the tenant). Previously, if a single DC server was used by multiple organizations, the licensed amounts were shared between them without any programmatic checks to ensure that each organization used the previously agreed amount of agents only.
This configuration option is an extension of the client's 'offline-mode', not a feature of the License Server.
This feature extends the use cases of your license file, but it does not replace it. You will still need a valid license file provided by Geomant. If you already have license for an older version of DC, a new file with the same volumes will be provided to you during the upgrade to 1.6+.
Defining Tenants
In order to define tenants, you will need to modify the 'tenants' file (it has no extension) next to the license file ('dc4crm.license.signed.xml' for DC4CRM) located in the Tomcat/lib folder. This tenant definition file can be modified at will and will get reloaded (no service restart required).
The signed license file limits supersede the tenant configuration in the sense that if your license file expires or has a lower limit than a tenant (or the sum of your tenants) for a Volume, consumption of the volume (i.e. login) will fail after the date or when the license file limit is exceeded by the total amount of consumption (logins) from all tenants. Consider the expiration/maximum limits of your license file before creating the 'tenants' file, so the settings here communicated to your tenants actually guarantee these limits.
Example 1 - Using Single Limit for Each Limit
The file contains a single JSON format object. As such, it starts and ends with braces. The object has a single field, an array called 'tenants'. This array contains the tenant objects. Tenant objects have an 'id', 'guid' and name field, and an array of product objects ('products'). Product objects have a name that is the same as the product name in your license file ('DC4CRM' for DC4CRM 1.6 and up). They have an array of volumes with each volume having a name found in your license file - the most important is the 'CTIAgents' which sets the amount of concurrent agents you can log in with. The limits array has limit objects with a maximum amount and an expiry date - the actual restriction on the concurrent usage for that tenant, product and volume it is contained by. The first example contains a single limit object for each volume. This should be sufficient if your tenant limits do not change often (or at all). Examples of how setting multiple limits can help to define monthly changing limits will be included after the first, basic example.
tenants - example 1
{ "tenants":[ { "id":"tenant1", "guid":"some_unique_id", "name":"First Tenant Ltd.", "products":[ { "name":"DC4CRM", "volumes":[ { "name":"CTIAgents", "limits":[ { "max":"50","expires": 2017-04-18} ] }, { "name":"ACRAgents", "limits":[ { "max":"10","expires": 2017-04-18} ] } ] } ] }, { "id":"tenant2", "name":"Tenant Two Ltd.", "guid":"this is unique too", "products":[ { "name":"DC4CRM", "volumes":[ { "name":"CTIAgents", "limits":[ { "max":"30","expires": 2017-04-18} ] }, { "name":"ACRAgents", "limits":[ { "max":"10","expires": 2017-04-18} ] } ] } ] } ]}
This file describes the limits of two tenant organizations: First Tenant Ltd. (id=tenant1, line 3 to 26) and Tenant Two Ltd. (id=tenant2, line 27 to 50).
Both have a single product, 'DC4CRM'. Since version 1.6, an installation will only need a single product license (previously, some GeoCCI features were licensed separately, this is now obsolete and not required). This means that each tenant will only have the one product (it still needs to be specified there).
Tenant 1 has a limit of 50 on CTIAgents, valid until 2017-04-18 (becomes
invalid at 23:59:59 that day). You will need to consider the expiration
dates set in your license file to set these.
Tenant 2 has a limit of 30 on CTIAgents. Together, they have 80. To
ensure that both can use the limit set here, the license file should
have at least 80 as the size of the CTIAgents volume.
Tenant 1 and 2 both have maximum 10 concurrent ACRAgents set. The license file should have 20.
All volumes here expire on 2017-04-18. The license file would probably have the same expiration date. If your tenants file have expiration dates before your license file's dates, you will need to update the tenants file to keep using your license to the full duration. Setting the tenants file to later dates is recommended, in this case, the license file expiration would be the source of the login error past the date.
Example 2 - Using Multiple Limits for the Same Volume
Replace the Volume object in tenant 1 from Example 1 with this object:
Example 2
{ "name":"CTIAgents", "limits":[ { "max":"30","expires": 2016-04-18} { "max":"40","expires": 2016-05-18} { "max":"50","expires": 2016-06-18} { "max":"30","expires": 2017-04-18} ]}
Notice that the limits list has multiple entries, each with a different 'max' and 'expires' value.
If you know that the limits of the tenants will change in the coming months/years, and have the exact value what they are going to be, you can use this to reduce the times you have to edit the file, storing these changes ahead of time. Otherwise, you could just change the tenant limits when needed / the information becomes available.
The meaning for the expires value is that the limit expires on the given date, and starts if this expire date is the smallest value when the previous limit expires, or is the absolute smallest value in its list when loading the file.
This list is neatly ordered, so it is easy to figure out when each limit would be valid:
| line # | starts | ends | max |
|---|---|---|---|
| 4 | n/a | 2016-04-18 | 30 |
| 5 | 2016-04-19 | 2016-05-18 | 40 |
| 6 | 2016-05-19 | 2016-06-18 | 50 |
| 7 | 2016-06-19 | 2017-04-18 | 30 |
So, the tenant has 30 agents until 2016-04-18 and between 2016-06-19 and 2017-04-18. There is a prediction of increased usage in the tenant within the two periods (line 5 and 6) and has been given 40 and 50 agents, respectively.
The same logic applies to the dates on the volumes in your license file if you requested different amount for different time periods. So, your license file could contain four CTIAgents Volumes with the same expiry dates and increases in volume.
If it is not the case, and it has a flat 80 volume, but you have decided to reallocate your Volumes to this tenant temporarily, you will need to modify the other tenant, too:
Example 2
{ "name":"CTIAgents", "limits":[ { "max":"50","expires": 2016-04-18} { "max":"40","expires": 2016-05-18} { "max":"30","expires": 2016-06-18} { "max":"50","expires": 2017-04-18} ]}
Your other tenant agreed to "give over" 10 and 20 volumes. This should probably be reflected in SLA or billing changes for those two months.
Frequently Asked Questions
Q: Where can I find my tenants file?
A: In your Tomcat/lib folder; usually "C:/Program Files/Apache Software
Foundation/Tomcat 8.0/lib". The license file (*.license.signed.xml) is
in the same folder. The file name is "tenants". It doesn't have an
extension.
Q: I don't have any tenants, I just want to use my old license file as
normal after upgrading to 1.6+. What do I need to do?
A: Nothing. The installing engineer will simply not create this file,
and the prduct will continue you function without tenant limits,
allowing you to continue using it with the same Volumes you have.
Q: Can I use the tenants file to set up post-paid/subscription type
billing; generate usage reports; enable online management of licenses,
etc.?
A: No. These are all planned features for the Geomant License Server
(release date TBA). The tenants file configuration is a simple,
middle-ground solution that allows using a single DC server for multiple
tenants, but without the complexity of connecting the server to a
Geomant License Server.
Q: Can I use the tenants file to extend my license that is about to
expire or increase my total licensed volume?
A: No, if your license is about to expire or it's limits need
increasing, you will need to contact Geomant or it's partner to update
it. After the purchase order, a new license will be provided for you.
You can edit the tenants file in advance if you want to to distribute
your new volumes / update expiration for tenants.
Q: Can I edit the tenants file without Geomant's assistance or
permission?
A: Yes. If you read this document, you should be able to edit/create
tenants, assign/modify the volumes, etc. If you have questions, feel
free to contact Geomant for consultation and/or assistance.
Q: I've accidentally modified/deleted my tenants file. Can it be rolled back?A: Not automatically, no. Always create a backup of this file before editing (i.e. copy it and rename the copy to tenants_backup_). Copy the backup file and rename it back to "tenants" (no extension) if you deleted your tenants file.
Q: I've finished editing and saved the file. What do I need to do to make the new limits / tenants live on the DC server?A: Nothing. Every time you modify and save the file, the license client re-reads it. This can be done during the day, functionality will not be affected.
Q: I've just set a lower limit, yet my tenant reportedly has more agents logged in than the new limit. Is this a bug?A: It isn't: agents do not get logged out due to the limit changing. However, no additional agents can log in while the tenant is above the limit. DC products using this licence client usually logs out agents if they close the browser, so you can expect the tenant's consumption to normalize the next day when agents try to log back in in the morning. You should notify your tenants of changes you make to the file; ideally, the agreements you have with your tenants will ensure that they only use the appropriate number of agents, and never see a license related login error message.
Q: The format of this file looks weird. What are all these braces and brackets?A: JSON is a widely used format for sending/storing structured data. The braces "{}" represent the start and end of objects. The brackets "[]" represent start and end of arrays. Objects and arrays can contain other objects and arrays. This nesting increases the number of brackets/braces.
Q: Can I create any number of tenants?A: Yes. There is no technical limitation on this, but you will probably want to keep your tenants to a logical minimum for easier management of limits (i.e. one per tenant, not one per each department / team of the tenant, unless you actually need to separate their usage limits).
Q: Is there an editor for the tenants file?A: Notepad++ is the recommended editor for tenants file. Any tool that allows syntax highlighting for JavaScript objects notation (JSON) can be used. Windows Notepad is not recommended.
Q: Where do I configure the product (DC4CRM, DCUA) to use the correct guid for each tenant to idetify them?A: Refer to product configuration entries in the Knowledge Base for details.
Q: I have agents connecting to the DC server from many different time-zones. Will they each see the Volume about to expire at the end of the day, their local time?A: No, the expiry date is determined by the DC server time: 23:59:59 of the day given, server local time, the volume will expire. If an agent, for example, is eight hours behind the server, he may no longer be able to log in after 4 PM if there is no new limit with a longer expiration date. Since the expiry happens at midnight, a few hours of time difference will not affect the agents during the workday.