Difference between revisions of "AppSuite:Capabilities"

(Testing the capabilities)
 
(18 intermediate revisions by 4 users not shown)
Line 11: Line 11:
 
'''Usecase'''
 
'''Usecase'''
  
You write a new UI app or plugin (chat module, for example) and want to make sure that only a specific set of users or contexts within the system can it.  
+
You write a new UI app or plugin (chat module, for example) and in addition, you want to make sure that only a specific set of users or contexts within the system are allowed to use it.  
  
 
''Example:'' Your chat app should only be available after a user has bought it in your online shop. To do so, you will need to implement the capabilities logic within your UI app or plugin and restrict it to a user or context marked accordingly (called "premium" in further examples).
 
''Example:'' Your chat app should only be available after a user has bought it in your online shop. To do so, you will need to implement the capabilities logic within your UI app or plugin and restrict it to a user or context marked accordingly (called "premium" in further examples).
Line 17: Line 17:
 
== Set a capability ==
 
== Set a capability ==
  
First, disable it for everyone as default (or enable it for everyone, depending on what your aim is). In <tt>/opt/open-xchange/[myproduct].properties</tt>:
+
First, disable it for everyone as default (or enable it for everyone, depending on what your aim is).  
 +
 
 +
In <tt>/opt/open-xchange/etc/[myproduct].properties</tt>:
  
 
   com.openexchange.capability.[myproduct]=false # off for everyone
 
   com.openexchange.capability.[myproduct]=false # off for everyone
  
Then enable it only for a specific user:
+
Then restart the OX Application Server and afterwards use the general OX AppSuite commandline tools to enable the capability/capabilities.
 +
 
 +
The commandline tools used in the following examples are located in:
 +
 
 +
  /opt/open-xchange/sbin
 +
 
 +
In this example, only for a specific user:
 +
 
 
   changeuser ... --config/com.openexchange.capability.[myproduct]=true
 
   changeuser ... --config/com.openexchange.capability.[myproduct]=true
  
Or for a full context:
+
...or for a full context:
 
   changecontext -c ... --config/com.openexchange.capability.[myproduct]=true
 
   changecontext -c ... --config/com.openexchange.capability.[myproduct]=true
  
  
Or give the capability to a context set:
+
...or set the capability to a context set:
  
 
   changecontext -c ... --taxonomy/types=premium
 
   changecontext -c ... --taxonomy/types=premium
  
in <tt>/opt/open-xchange/etc/contextSets/premium.yml</tt>:
+
To get the capability/capabilities working for context sets (like above), you also need to edit the contextSet files in:
 +
 
 +
  <tt>/opt/open-xchange/etc/contextSets/premium.yml</tt>
 +
 
 +
And add the corresponding capability/capabilities:
  
 
   premium:
 
   premium:
     com.openexchange.config.capability.[myproduct]: true
+
     com.openexchange.capability.[myproduct]: true
 
     withTags: premium
 
     withTags: premium
 +
 +
Then restart the OX Application Server!
  
 
== Query capabilities via the HTTP API ==
 
== Query capabilities via the HTTP API ==
Line 43: Line 58:
 
   GET /appsuite/api/capabilities?action=all&session=991fd40f635b45...
 
   GET /appsuite/api/capabilities?action=all&session=991fd40f635b45...
 
Response:
 
Response:
   {"data":[{"id":"oauth","attributes":{}},{"id":"webmail","attributes":{}},{"id":"document_preview","attributes":{}},{"id":"printing","attributes":{}},{"id":"spreadsheet","attributes":{}},{"id":"gab","attributes":{}},{"id":"multiple_mail_accounts","attributes":{}},{"id":"publication","attributes":{}},{"id":"rss_bookmarks","attributes":{}},{"id":"linkedin","attributes":{}},{"id":"filestore","attributes":{}},{"id":"ical","attributes":{}},{"id":"rt","attributes":{}},{"id":"olox20","attributes":{}},{"id":"forum","attributes":{}},{"id":"active_sync","attributes":{}},{"id":"conflict_handling","attributes":{}},{"id":"rss_portal","attributes":{}},{"id":"oxupdater","attributes":{}},{"id":"infostore","attributes":{}},{"id":"contacts","attributes":{}},{"id":"collect_email_addresses","attributes":{}},{"id":"facebook","attributes":{}},{"id":"drive","attributes":{}},{"id":"rss","attributes":{}},{"id":"pinboard_write_access","attributes":{}},{"id":"mobility","attributes":{}},{"id":"calendar","attributes":{}},{"id":"participants_dialog","attributes":{}},{"id":"edit_public_folders","attributes":{}},{"id":"text","attributes":{}},{"id":"groupware","attributes":{}},{"id":"msisdn","attributes":{}},{"id":"carddav","attributes":{}},{"id":"tasks","attributes":{}},{"id":"portal","attributes":{}},{"id":"mailfilter","attributes":{}},{"id":"read_create_shared_folders","attributes":{}},{"id":"vcard","attributes":{}},{"id":"pim","attributes":{}},{"id":"caldav","attributes":{}},{"id":"projects","attributes":{}},{"id":"usm","attributes":{}},{"id":"webdav","attributes":{}},{"id":"dev","attributes":{}},{"id":"delegate_tasks","attributes":{}},{"id":"freebusy","attributes":{}},{"id":"subscription","attributes":{}},{"id":"linkedinPlus","attributes":{}},{"id":"autologin","attributes":{}},{"id":"webdav_xml","attributes":{}},{"id":"twitter","attributes":{}}]}
+
   {"data":[{"id":"oauth","attributes":{}},{"id":"webmail","attributes":{}},{"id":"document_preview","attributes":{}},{"id":"printing","attributes":{}},{"id":"spreadsheet","attributes":{}},{"id":"gab","attributes":{}},{"id":"multiple_mail_accounts","attributes":{}},{"id":"publication","attributes":{}},{"id":"rss_bookmarks","attributes":{}},{"id":"linkedin","attributes":{}},{"id":"filestore","attributes":{}},{"id":"ical","attributes":{}},{"id":"rt","attributes":{}},{"id":"olox20","attributes":{}},{"id":"forum","attributes":{}},{"id":"active_sync","attributes":{}},{"id":"conflict_handling","attributes":{}},{"id":"rss_portal","attributes":{}},{"id":"oxupdater","attributes":{}},{"id":"infostore","attributes":{}},{"id":"contacts","attributes":{}},{"id":"collect_email_addresses","attributes":{}},{"id":"drive","attributes":{}},{"id":"rss","attributes":{}},{"id":"pinboard_write_access","attributes":{}},{"id":"mobility","attributes":{}},{"id":"calendar","attributes":{}},{"id":"participants_dialog","attributes":{}},{"id":"edit_public_folders","attributes":{}},{"id":"text","attributes":{}},{"id":"groupware","attributes":{}},{"id":"msisdn","attributes":{}},{"id":"carddav","attributes":{}},{"id":"tasks","attributes":{}},{"id":"portal","attributes":{}},{"id":"mailfilter","attributes":{}},{"id":"read_create_shared_folders","attributes":{}},{"id":"vcard","attributes":{}},{"id":"pim","attributes":{}},{"id":"caldav","attributes":{}},{"id":"projects","attributes":{}},{"id":"usm","attributes":{}},{"id":"webdav","attributes":{}},{"id":"dev","attributes":{}},{"id":"delegate_tasks","attributes":{}},{"id":"freebusy","attributes":{}},{"id":"subscription","attributes":{}},{"id":"linkedinPlus","attributes":{}},{"id":"autologin","attributes":{}},{"id":"webdav_xml","attributes":{}},{"id":"twitter","attributes":{}}]}
  
 
Here <tt>id</tt> is the name of the capability.
 
Here <tt>id</tt> is the name of the capability.
 +
 +
Note that the LinkedIn support was removed since 7.10.0
  
 
== Query capabilities in the UI ==
 
== Query capabilities in the UI ==
 
   require(['io.ox/core/capabilities'], function (cap) { if cap.has('[myproduct]' { ... } );
 
   require(['io.ox/core/capabilities'], function (cap) { if cap.has('[myproduct]' { ... } );
  
== Require the capabilities in your UI manifest ==
+
To just list all:
 +
 
 +
  _(ox.serverConfig.capabilities).pluck("id").sort();
 +
 
 +
== Require the capabilities in your UI manifest file ==
 
   {
 
   {
 
     namespace: ...
 
     namespace: ...
Line 56: Line 77:
 
   }
 
   }
  
The plugin will only be loaded if the capability is set for the specific user.
+
Now your plugin will only be loaded if the capability '[myproduct]' is set for a specific user, context, context set.
  
 +
== Testing the capabilities ==
  
== Testing the capabilities ==
+
* For testing purposes use an URL parameter to test capabilities.
 +
 
 +
Add the following parameter to your AppSuite URL in the browser to activate:
 +
 
 +
  &cap=[myproduct]
 +
 
 +
or use
 +
 
 +
  &disableFeature=[myproduct]
  
* For testing purposes use these 2 easy steps:
+
to disable a certain capability.
  
  Add the "&cap=[myproduct]" URL parameter in your AppSuite browser tab
+
In general, after adding those URL parameters, you need to reload the UI to temporarly test/enable the set capability.
  Reload the UI to temporarly test/enable a capability.
 
  
 
== Further informations ==  
 
== Further informations ==  
 
+
* See the dedicated wiki page of the [[ConfigCascade]] mechanism for more details.
* Similarly, you can disable a capability with &disableFeature=[myproduct]
 
 
* If you want to know about existing capabilities and the way they are used for upsell, see [[AppSuite:Upsell#Capabilities_and_Upsell_triggers]]
 
* If you want to know about existing capabilities and the way they are used for upsell, see [[AppSuite:Upsell#Capabilities_and_Upsell_triggers]]
  

Latest revision as of 15:55, 26 February 2020



Synopsis: How to use capabilities so that your new AppSuite plugin can be enabled or disabled.

What are capabilities?

Usecase

You write a new UI app or plugin (chat module, for example) and in addition, you want to make sure that only a specific set of users or contexts within the system are allowed to use it.

Example: Your chat app should only be available after a user has bought it in your online shop. To do so, you will need to implement the capabilities logic within your UI app or plugin and restrict it to a user or context marked accordingly (called "premium" in further examples).

Set a capability

First, disable it for everyone as default (or enable it for everyone, depending on what your aim is).

In /opt/open-xchange/etc/[myproduct].properties:

 com.openexchange.capability.[myproduct]=false # off for everyone

Then restart the OX Application Server and afterwards use the general OX AppSuite commandline tools to enable the capability/capabilities.

The commandline tools used in the following examples are located in:

 /opt/open-xchange/sbin

In this example, only for a specific user:

 changeuser ... --config/com.openexchange.capability.[myproduct]=true

...or for a full context:

 changecontext -c ... --config/com.openexchange.capability.[myproduct]=true


...or set the capability to a context set:

 changecontext -c ... --taxonomy/types=premium

To get the capability/capabilities working for context sets (like above), you also need to edit the contextSet files in:

 /opt/open-xchange/etc/contextSets/premium.yml

And add the corresponding capability/capabilities:

 premium:
    com.openexchange.capability.[myproduct]: true
    withTags: premium

Then restart the OX Application Server!

Query capabilities via the HTTP API

Query:

 GET /appsuite/api/capabilities?action=all&session=991fd40f635b45...

Response:

 {"data":[{"id":"oauth","attributes":{}},{"id":"webmail","attributes":{}},{"id":"document_preview","attributes":{}},{"id":"printing","attributes":{}},{"id":"spreadsheet","attributes":{}},{"id":"gab","attributes":{}},{"id":"multiple_mail_accounts","attributes":{}},{"id":"publication","attributes":{}},{"id":"rss_bookmarks","attributes":{}},{"id":"linkedin","attributes":{}},{"id":"filestore","attributes":{}},{"id":"ical","attributes":{}},{"id":"rt","attributes":{}},{"id":"olox20","attributes":{}},{"id":"forum","attributes":{}},{"id":"active_sync","attributes":{}},{"id":"conflict_handling","attributes":{}},{"id":"rss_portal","attributes":{}},{"id":"oxupdater","attributes":{}},{"id":"infostore","attributes":{}},{"id":"contacts","attributes":{}},{"id":"collect_email_addresses","attributes":{}},{"id":"drive","attributes":{}},{"id":"rss","attributes":{}},{"id":"pinboard_write_access","attributes":{}},{"id":"mobility","attributes":{}},{"id":"calendar","attributes":{}},{"id":"participants_dialog","attributes":{}},{"id":"edit_public_folders","attributes":{}},{"id":"text","attributes":{}},{"id":"groupware","attributes":{}},{"id":"msisdn","attributes":{}},{"id":"carddav","attributes":{}},{"id":"tasks","attributes":{}},{"id":"portal","attributes":{}},{"id":"mailfilter","attributes":{}},{"id":"read_create_shared_folders","attributes":{}},{"id":"vcard","attributes":{}},{"id":"pim","attributes":{}},{"id":"caldav","attributes":{}},{"id":"projects","attributes":{}},{"id":"usm","attributes":{}},{"id":"webdav","attributes":{}},{"id":"dev","attributes":{}},{"id":"delegate_tasks","attributes":{}},{"id":"freebusy","attributes":{}},{"id":"subscription","attributes":{}},{"id":"linkedinPlus","attributes":{}},{"id":"autologin","attributes":{}},{"id":"webdav_xml","attributes":{}},{"id":"twitter","attributes":{}}]}

Here id is the name of the capability.

Note that the LinkedIn support was removed since 7.10.0

Query capabilities in the UI

 require(['io.ox/core/capabilities'], function (cap) { if cap.has('[myproduct]' { ... } );

To just list all:

 _(ox.serverConfig.capabilities).pluck("id").sort();

Require the capabilities in your UI manifest file

 {
    namespace: ...
    requires: '[myproduct]'
 }

Now your plugin will only be loaded if the capability '[myproduct]' is set for a specific user, context, context set.

Testing the capabilities

  • For testing purposes use an URL parameter to test capabilities.

Add the following parameter to your AppSuite URL in the browser to activate:

 &cap=[myproduct]

or use

 &disableFeature=[myproduct]

to disable a certain capability.

In general, after adding those URL parameters, you need to reload the UI to temporarly test/enable the set capability.

Further informations