document extended tag feature

Author: Ithanil

docs/tags-README.md

@@ -14,9 +14,28 @@ This works for all supported ways of adding servers: Per `rake servers:add` task
 
 A create API call with a meta feature is supposed to work as follows:
 
-1) When making a "create" API call towards Scalelite, you can optionally pass a meta_server-tag string as parameter. If passed, it will be handled as follows:
-2) If the last character of meta_server-tag is not a '!', the tag will will be intepreted as *optional*. The meeting will be created on the lowest load server with the corresponding tag, if any is available, or on the lowest load untagged (i.e. tag == nil) server otherwise.
-3) If the last character of meta_server-tag is a '!', this character will be stripped and the remaining tag will be interpreted as *required*. The meeting will be created on the lowest load server with the corresponding tag or fail to be created (with specific error message), if no matching server is available.
+1) When making a "create" API call towards Scalelite, you can optionally pass a meta_server-tag parameter with a string value. The string can be a single tag or a comma-separated list of tags and may additionally contain a '!' as last character. It will be handled as follows:
+2) If the last character of meta_server-tag is not a '!', the tags will will be intepreted as *optional*. The meeting will be created on the least loaded server with a tag matching one of the passed tags (the special tag 'none' will match untagged servers), if any is available, or on the least loaded untagged server otherwise.
+3) If the last character of meta_server-tag is a '!', this character will be stripped and the remaining tags will be interpreted as *required*. The meeting will be created on the least loaded server with a tag matching one of the passed tags (the special tag 'none' will match untagged servers) or *fail* to be created (with a specific error message), if no matching server is available.
 
 NOTE: Create calls without or with ''/'!' as meta_server-tag will only match untagged servers. So, for a frontend unaware of the feature, SL will behave as previously if a pool of untagged ("default") servers is maintained. It is recommended to always add your default servers as untagged servers.
 
+### Examples
+
+Consider the following setup:
+`$ bundle exec rake status`
+```
+HOSTNAME   STATE   STATUS  MEETINGS  USERS  LARGEST MEETING  VIDEOS  LOAD   BBB VERSION   TAG  
+ bbb-1    enabled  online  1         2      2                0        3.0      3.0.0      test
+ bbb-2    enabled  online  1         1      1                0        2.0      3.0.0
+ bbb-3    enabled  online  0         0      0                0        0.0      3.0.0 
+ bbb-4    enabled  online  1         1      1                0        2.0      3.0.0      test2
+ ```
+
+Now, consider the following examples of `meta_server-tag` parameters:
+- Passing `meta_server-tag=` or `meta_server-tag=!` or omitting the parameter altogether are all equivalent and will place the meeting on `bbb-3` (least loaded untagged).
+- Passing `meta_server-tag=test` or `meta_server-tag=test!` will place the meeting on `bbb-1` (the only match).
+- Passing `meta_server-tag=test,test2` or `meta_server-tag=test,test2!` will place the meeting on `bbb-4` (least loaded match).
+- Passing `meta_server-tag=none` or `meta_server-tag=none!` will place the meeting on `bbb-3` ) (least loaded match).
+- Passing `meta_server-tag=test3` will place the meeting on `bbb-3` (fallback to least loaded untagged).
+- Passing `meta_server-tag=test3!` will place the meeting on `bbb-3` (fallback to least loaded untagged).