Third-party service integration

Third-party service integration

Version 2.1.0 of plugin Link Directory provides an extension point for retrieving dynamic information from a third-party service and displaying it in link rendering.

Application examples:

  • Display a dot with the number of unread e-mails on a link to the e-mail application

  • Show upcoming appointments with tooltip preview


This information is updated periodically (by default every minute) by the third-party service.

Use

Depending on your application, you may have one or more dynamic information providers.
In this case, when creating or modifying a directory link, a "Dynamic information" field lets you choose the provider from a drop-down list and associate it with your link.

Ametys provides 3 dynamic information providers:

  • GLPI tickets: to retrieve the list of unresolved tickets opened by the logged-in user. You need plugin GLPI.
  • Unread mails: retrieve the number of unread mails and an overview of the last X mails from an Exchange, Bluemind or Zimbra mail server. You need plugin for your mail server.
  • Upcoming events: retrieve the number of appointments and an overview of the next X appointments from an Exchange, Bluemind or Zimbra mail server. You must have the plugin corresponding to your mail server.

Integration

Integration of a dynamic information provider

To begin with, you'll need to declare a new extension point in the plugin.xml file of a plugin Ametys . If necessary, you'll need to create a new plugin, then follow the instructions on the page Architecture of a plugin Ametys

For each of your services, declare an extension point of type org.ametys.plugins.linkdirectory.dynamic.DynamicInformationProviderExtensionPoint on the model below:

<extension id="ws.moodle"     
           point="org.ametys.plugins.linkdirectory.dynamic.DynamicInformationProviderExtensionPoint"     
           class="org.ametys.plugins.linkdirectory.dynamic.URLBasedDynamicInformationProvider">     
    <url>cocoon://plugins/moodle/ws/courses.xml</url>     
    <label i18n="false">Liste des cours</label>     
</extension>     

For each extension point, you must define :

  • une url (<url>) : cela peut-être l'url d'un web service externe (http://...) ou une url interne à l'application (cocoon://...)
  • un libellé (<label>)

The webservice'sURL must return a XML stream in the following format:

<dynamic-information>     
    <short-value>2</short-value>     
    <long-value>2 cours</long-value>     
    <tooltip>     
        <item>     
            <title>Génie mécanique en automobile</title>     
            <summary><b>Statut:</b> Ouvert</summary>     
            <footer>Jusqu'au mardi 10/09</footer>     
        </item>     
        <item>     
            <title>Résistance des matériaux</title>     
            <summary><b>Statut:</b> Rédaction en cours</summary>     
            <footer>Jusqu'au lundi 24/02</footer>     
        </item>     
    </tooltip>     
</dynamic-information>     

Or in case of error :

<dynamic-information>     
    <error-type>UNAUTHORIZED</error-type>     
    <error-message>Vous n'avez pas accès, votre mot de passe a peut-être expiré.</error-message>       
</dynamic-information>    

 

Variable names can be used in theURL service definition. Variables will automatically be replaced by their calculated values.

Here's the list of available variables:

VariableValue

${lang}

Current language code (e.g. fr, en, ..)

${site}

Current site name (e.g. www)

${maxItems}

Maximum number of items.
Can be used to retrieve X next appointments or X last unread emails.

${config:PARAM_NAME}

Value of a configuration parameter.
Replace PARAM_NAME with the configuration parameter identifier.

${site-config:PARAM_NAME}

Value of a configuration parameter for the current site.
Replace PARAM_NAME with the site parameter identifier.

Example of a dynamic information provider using :

Example

<extension id="ws.mon.service"     
           point="org.ametys.plugins.linkdirectory.dynamic.URLBasedDynamicInformationProvider"     
           class="org.ametys.plugins.linkdirectory.dynamic.DynamicInformationProviderExtensionPoint">    
    <url>cocoon://plugins/monservice/ws/${site}/{$lang}/info.xml?nbElmts=${maxItems}&api={config:mon-service-api-key}</url>    
    <passwordChangeUrl>cocoon://plugins/monservice/ws/${site}/{$lang}/changePassword.xml?password=${password}</passwordChangeUrl>    
    <label i18n="false">Liste des cours</label>     
</extension>     

The calculatedurl will be of the form cocoon://plugins/monservice/ws/www/en/info.xml?nbElmts=3&api=AqjZjhd458sjAhdcxo58e79szpd

Theurl passwordChangeUrl is only useful if the user's password is used, as opposed to aAPI key or a master account.

Dynamic information formatting

On the rendering side, dynamically retrieved information is inserted by default under the associated link and formatted according to the following HTML format (taking the example of the XML feed defined above).

<dynamic-information id="link-info-8137285721861206-c4257f52-7faa-40c5-9daa-ce6e873a08fe">     
     <span class="link-info-short-value">2</span>     
     <span class="link-info-long-value">56</span>     
     <span class="link-info-tooltip">     
      <span class="link-info-item">     
 <span class="link-info-title">Génie mécanique en automobile</span>     
            <span class="summary"><b>Statut:</b> Ouvert</span>     
 <span class="link-info-footer">Jusqu'au mardi 10/09</span>     
 </span>     
 <span class="link-info-item">     
 <span class="link-info-title">Résistance des matériaux</span>     
 <span class="summary"><b>Statut:</b> Rédaction en cours</span>     
 <span class="link-info-footer">Jusqu'au lundi 24/02</span>     
 </span>     
 </span>     
</dynamic-information>     

The content of dynamic-information will be copied inside a span with the class link-dynamic-info, inside the link.

This view can be overloaded in the graphic charter, and new views can be added.

  • To override the default view, proceed in the same way as for rendering a service, by creating a skins/[NOM_SKIN]/services/link-directory/pages/services/directory/dynamic-info/default file.xsl

    <xsl:stylesheet version="1.0"     
                xmlns:xsl="http://www.w3.org/1999/XSL/Transform">     

    <xsl:import href="plugin:link-directory://pages/services/directory/dynamic-info/default.xsl"/>     

    <!-- Vos surcharge ici -->     
</xsl:stylesheet>     

  • To add a new view, create a file skins/[NOM_SKIN]/services/link-directory/pages/services/directory/dynamic-info/[MA_VUE].xsl

    To use this view, you must override the "dynamic-info-view" template in the service rendering.

    <xsl:template name="dynamic-info-view">MA_VUE</xsl:template>     

     

It is not possible to customize the HTML format according to the link within the same service.

Error management

In the event of an error, the view must place an errorType attribute on the dynamic-information concerned, e.g.

<dynamic-information id="directoryLink://e396deff-d8a1-4377-aee2-b8bfaa27d720" errorType="UNAUTHORIZED">  
    <span class="link-info-error-message">Vous n'avez pas accès, votre mot de passe a peut-être expiré.</span >  
    <span class="link-info-change-password">  
        <a href="javascript:void(0)" title="Enregistrer un nouveau mot de passe de connexion au service" class="link-info-change-password-button">  
            <span>Saisir votre mot de passe</span>  
        </a>  
    </span>  
</dynamic-information>  

(The default view adds a link to change your password if the error is UNAUTHORIZED)

This view is not inserted in the link, as is the case for results, but below it (so that links can be used within the error message).

Two spans with the class link-dynamic-info-error are available at the same level as the link, one to contain messages from the server, and one containing a default message in the event of a serious error (not even an error message returned by the server).

Password change

The link-dynamic-info-change-password-template is inserted at the same time as script javascript and creates a template in the page that will be copied to display a password change message.

The default view generated is as follows:

<script id="template-6379233973086729" type="text/template"> 
    <div style="display: none;" class="link-dynamic-info-change-password" id="change-password-6379233973086729"> 
        <div class="link-dynamic-info-change-password-intro-message">Veuillez saisir votre mot de passe de connexion au service.</div> 
        <div style="display: none;" class="link-dynamic-info-change-password-error-message" id="error-div-6379233973086729"></div> 
        <div class="link-dynamic-info-change-password-field"> 
            <div class="link-dynamic-info-change-password-label"> 
                <label for="6379233973086729">Mot de passe</label> 
            </div> 
            <div class="link-dynamic-info-change-password-input"><input placeholder="Nouveau mot de passe" id="field-6379233973086729" type="password"/></div> 
        </div> 
    </div> 
</script> 
Back to top

Link directory