Difference between revisions of "AppSuite:Capabilities"

(What are capabilities?)
 
(28 intermediate revisions by 5 users not shown)
Line 9: Line 9:
 
== What are capabilities? ==  
 
== What are capabilities? ==  
  
Usecase:
+
'''Usecase'''
  
You write a new UI app or plugin for OX AppSuite and want to make sure that only specific OX users or OX contexts can use that app or plugin. For example, after someone purchased it via a web shop or similar. Of course, it is also possible to make a plugin / app available for all users of an OX system.
+
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 ==
 
== 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 41: 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 capabilities in a manifest ==
+
To just list all:
 +
 
 +
  _(ox.serverConfig.capabilities).pluck("id").sort();
 +
 
 +
== Require the capabilities in your UI manifest file ==
 
   {
 
   {
 
     namespace: ...
 
     namespace: ...
Line 54: 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 ==
 +
 
 +
* 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]
  
== Further notes ==
+
or use
* For testing purposes, you can use the &cap=[myproduct] url parameter to enable a capability. Remember to refresh.
+
 
* Similarly, you can disable a capability with &disableFeature=[myproduct]
+
  &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 ==  
 +
* See the dedicated wiki page of the [[ConfigCascade]] mechanism for more details.
 
* 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]]
 +
 +
 +
  
 
[[Category: AppSuite]]
 
[[Category: AppSuite]]

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