Difference between revisions of "AppSuite:Capabilities"

(Set a capability)
 
(12 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 19: Line 19:
 
First, disable it for everyone as default (or enable it for everyone, depending on what your aim is).  
 
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>:
+
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
Line 41: Line 41:
 
   changecontext -c ... --taxonomy/types=premium
 
   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  
+
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>:
+
   <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
  
Line 56: 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 69: 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