Extensions
Any permet d'ajouter des extensions personnalisées. Il y a deux types d’extensions :
- Les appels REST qui peuvent faire des appels aux REST API Any ou à des appels REST externes
- Les extensions HTML qui peuvent être utilisées comme une section, un onglet, une tuile dédiée ou appelées à partir d'un menu et ouvertes dans une boîte de dialogue.
Ce document décrit ce qui peut être fait avec les extensions et comment vous pouvez générer votre propre extension.
Extensions basées sur les appels REST
Ces extensions permettent d’appeler :
- Les API REST de Any qui permettent notamment de créer des rooms, des groupes ou mettre à jour un document.
- Les URLs externes qui permettent d’exécuter des actions personnalisées.
Dans Any 17 et les versions précédentes, les appels aux APIs REST Any étaient faits dans un module dédié appelé « Script ». Il a été fusionné avec les extensions dans Any 18.
Pour configurer les appels aux APIs REST Any, veuillez-vous référer à la documentation sur les APIs REST Any.
Pour configurer les appels REST externes, vous devez définir une URL qui sera appelée. Cette URL aura des paramètres qui seront ajoutés automatiquement (ils sont décrits dans le chapitre Paramètre d'URL).
Pour rentrer l'URL et ses paramètres :
- Selectionner Type d'extension : Appel REST
- Dans le tableau tout en bas, cliquer sur le + pour créer une ligne
- Sélectionner un service REST
- Cliquer sur Aucun paramètres
Vous pouvez également mettre vos propres paramètres dans l’URL en utilisant les wildcards ${} (par exemple ${core.name} ou ${user.login}) pour récupérer des données contextuelles. Vous pouvez également utiliser ces wildcards dans les en-têtes http ou dans l’objet request.
Les appels REST externes peuvent déclencher des actions dans l’interface de Any en retournant du JSON dans leur réponse.
Si plusieurs appels REST sont réalisés de manière chainée, seul le JSON du dernier appel REST sera évalué.
Le JSON qui peut être renvoyé est décrit dans le chapitre Déclancher toutes les actions des extensions.
Extensions HTML
Dans Any, les extensions permettent d'intégrer des applications web personnalisées sous forme de sections dédiées ou dans une boîte de dialogue ouverte depuis un menu.
Les extensions sont intégrées dans Any avec une iframe qui ouvrira l'application web personnalisée intégrée dans Any. Il n'y a aucune limitation en termes de technologie que vous souhaitez utiliser pour votre application Web personnalisée tant qu'elle peut être affichée dans un navigateur Internet.
Dans la configuration des extensions de Any, vous devez définir l'URL qui doit être ouverte dans l'iframe. Cette URL aura des paramètres ajoutés automatiquement (décrits dans le chapitre Paramètre d'URL) mais vous pouvez également ajouter vos propres paramètres d'URL.
Paramètres d'URL
À la fin de l'URL de l'extension HTML et à la fin des URLs des appels externes REST, Any ajoutera automatiquement des paramètres de requête liés au contexte utilisateur.
S'il existe déjà des paramètres de requête dans l'URL configurée, les paramètres suivants seront ajoutés après eux.
Les paramètres suivants seront toujours ajoutés automatiquement dans l'URL :
- origin : contiendra la valeur de l'origine de l'URL Any (protocole + nom d'hôte + port).
L'origine doit être utilisée pour envoyer des messages de l'extension à Any. - source_url : URL complète de la page contenant la section et éventuellement la room où se trouve l'utilisateur. Elle est construite sur l'URL publique du serveur telle que définie dans les paramètres du serveur, afin de rester joignable depuis l'extérieur. Si celle-ci n'est pas renseignée, l'adresse utilisée par le navigateur.
- user : nom complet de l'utilisateur actuel.
- login : login de l’utilisateur actuel.
- ticket : ticket à utiliser pour vérifier la session utilisateur (utilisable une seule fois).
- application : nom de l'application en cours.
- locale : paramètres régionaux de l'utilisateur.
Si l'extension est utilisée dans un menu de sélection ou de sélection multiple, le paramètre suivant sera ajouté :
- selection : liste des ID de contenu sélectionnés.
Déclencher toutes les actions des extensions
Il est possible de déclencher des actions Any à partir de votre extension en retournant du JSON. Le JSON retourné définira l’action exécutée.
Depuis une extension HTML
Si vous souhaitez déclencher une action depuis une extension HTML, vous devez envoyer à Any des messages depuis l'iframe.
Les messages peuvent être envoyés à l'aide de la fonction JS :
window.parent.postMessage({...}, origin);
Cette fonction permet d'envoyer du JSON et nécessite une origine pour fonctionner.
Pour pouvoir déclencher des actions quelconques, vous devez utiliser comme origine la valeur du paramètre origin décrit dans le chapitre Paramètre d'URL.
Depuis un appel REST externe
Si vous souhaitez déclencher une action depuis un appel REST externe, l’appel doit retourner un JSON en fonction de l'action appelée. Les actions possibles qui peuvent être déclenchées, et leurs JSON de retour, sont décrites dans les chapitres suivants.
Visualisation
Il est possible de déclencher la vue du contenu du document.
JSON à renvoyer :
{
"event_type": "view",
"id": "g_c_f7e9663b-c08b-4ca9-8d90-1d8b3444e9c5",
"title": "Document preview"
}
Champs requis :
| Nom du champ | Type | Obligatoire | Description |
|---|---|---|---|
| event_type | String | X | Doit être défini comme view |
| id | String | X | Doit contenur le document core.object_id que vous souhaitez afficher |
| title | String | Peut contenir une valeur qui sera affichée en tant que titre de la boîte de dialogue contextuelle d'affichage dans Any au lieu de « Preview ». |
Recharger la sélection
Il est possible de déclencher le rafraichissement du contenu sélectionné dans Any, par exemple si vous souhaitez afficher dans Any certaines modifications apportées par l'extension. Ce type d'action ne fonctionnera que pour les extensions appelées à partir du menu de sélection ou de sélection multiple. Affichez le contenu du document en renvoyant le JSON suivant :
JSON à renvoyer :
{
"event_type": "refresh",
"ids": ["g_c_8d90-1d8b3444e9c5", "g_c_8d90-1d8b3444e9c5"]
}
Champs requis :
| Nom du champ | Type | Obligatoire | Description |
|---|---|---|---|
| event_type | String | X | Doit être défini sur refresh |
| ids | Tableau de strings | X | Doit contenir un tableau de documents core.object_id que vous souhaitez actualiser dans Any. Ces documents doivent figurer dans la liste des documents. |
Localiser
Il est possible de déclencher une localisation de documents dans leur room .
JSON à renvoyer :
{
'event_type': 'locate',
'ids': ['g_c_8d90-1d8b3444e9c5',' g_c_8d90-1d8b3444e9c5'],
'room_id': 'demo_room_001',
'filters': [{ 'name':'core.object_type','comp': 'eq','value':'procedure'}],
'keywords': 'my searched term'
}
Champs requis :
| Nom du champ | Type | Obligatoire | Description |
|---|---|---|---|
| event_type | String | X | Doit être défini comme locate |
| ids | Tableau de Strings | X | Doit contenir un tableau de documents core.object_id que vous souhaitez localiser |
| room_id | String | Peut contenir un ID de room pour forcer l'emplacement à être dans cette room. | |
| filters | Tableau de filters | Peut contenir un tableau d'objets filtres pour ajouter des filtres supplémentaires dans la room où les documents seront situés. | |
| keywords | String | Peut contenir des termes qui seront ajoutés à la barre de recherche dans la room et recherchés. |
Les filtres sont des objets JSON définis de cette façon :
| Nom du champ | Type | Obligatoire | Description |
|---|---|---|---|
| name | String | X | Nom des métadonnées sur lesquelles vous souhaitez filtrer, telles que « core.name » ou « extended.country » |
| comp | String | X | Type de comparateur que vous souhaitez utiliser. Les comparateurs disponibles sont : eq : vérifie si les métadonnées sont égales à la valeur. Doit être utilisé avec une valeur String. ne : vérifie si les métadonnées ne sont pas égales à la valeur. Doit être utilisé avec une valeur String. contains : vérifie si les métadonnées contiennent la valeur. Doit être utilisé avec une valeur String. in : vérifie si les métadonnées sont égales à l'une des valeurs. Doit être utilisé avec un tableau de chaîne comme valeur. ni : vérifie si les métadonnées ne sont pas égales aux valeurs. Doit être utilisé avec un tableau de chaîne comme valeur. |
| value | String or Array of String | X | Valeur que vous souhaitez comparer aux métadonnées. |
Rechercher
Il est possible de déclencher une localisation de documents dans leur room.
JSON à renvoyer :
{
'event_type': 'search',
'room_id': 'demo_room_001',
'filters': [{ 'name':'core.object_type','comp': 'eq','value':'procedure'}],
'keywords': 'my searched term'
}
Le JSON qui doit être envoyé pour déclencher cette action doit avoir les champs suivants :
| Nom du champ | Type | Obligatoire | Description |
|---|---|---|---|
| event_type | String | X | Doit être défini comme search |
| room_id | String | Peut contenir un ID de room pour forcer l'exécution de la recherche dans cette room. Si aucun room_id n'est spécifiée, la recherche sera exécutée dans la section de recherche globale. | |
| filters | Tableau de filters | Peut contenir un tableau d'objets de filtre pour ajouter des filtres supplémentaires où les documents seront recherchés. | |
| keywords | String | Peut contenir des termes qui seront ajoutés à la barre de recherche dans la room et recherchés. |
Exemples d'extension
Any est fourni avec deux exemples d'extension qui permettent d'ajouter une carte dans Any, l'un doit être utilisé comme une section, l'autre doit être utilisé dans le menu de sélection et de sélection multiple. Le code source peut être utilisé comme exemple de création d'une extension Any.
Section Carte
Cette extension est stockée dans le fichier map-section.html, fichier fourni dans Any - Extension Samples.zip.
Le but de cette extension est de pouvoir rechercher des contenus en mettant un marqueur sur une ville puis en effectuant une recherche sur une métadonnée qui est passée en paramètre.
Pour pouvoir utiliser cette extension, vous devez configurer l'URL comme ceci :
https://<server>:port/any-extensions/map-section.html?city_metadata=<métadonnées contenant le nom de la ville>
Une fois que vous aurez ajouté l'extension dans le module de section, vous pourrez voir ceci :
Dans cette extension, lorsque vous cliquez sur le bouton, la fonction suivante est exécutée pour déclencher une recherche dans Any :
//Fonction utilisée pour déclencher une recherche dans Any
var searchDocuments = function() {
// We extract the city name
var city = place_name.split(', ')[0];
//We create an array of filters objects
var filters = [
{ 'name': cityMetadata, 'comp': 'eq', 'value': city }
];
//We send a message back to Any by specifying the origin sent as parameter
window.parent.postMessage({
'event_type': 'search',
'filters': filters
}, origin);
}
Dans cette fonction, nous créons un tableau avec un filtre et envoyons le message à Any en utilisant l'origine transmise comme paramètres.
Boîte de dialogue Carte
Cette extension est stockée dans le fichier map-dialog.html, fourni dans l'archive Any - Extension Samples.zip.
Le but de cette extension est de pouvoir localiser sur la carte la valeur d'une métadonnée qui contient un nom de ville. Le nom des métadonnées est transmis en tant que paramètre.
Pour pouvoir utiliser cette extension, vous devez configurer l'URL comme ceci :
https://<server>:port/any-extensions/map-dialog.html?city_metadata=extended.city&country_metadata=extended.country
Une fois que vous aurez ajouté l'extension dans le module de section, vous pourrez voir ceci :
Cette extension utilise l'API Any REST, donc pour qu'elle fonctionne correctement, l'utilisateur actuel doit avoir le rôle « Utilisateur de l'API REST » et vous devez également activer la « Génération de jetons Web JSON » dans le module de stratégie de sécurité.
Cette extension fonctionne de la façon suivante :
- Tout d'abord, nous récupérons le jeton Web JSON pour pouvoir authentifier l'API REST et nous stockons le jeton à envoyer en tant qu'en-tête.
var postData = { 'login': login, 'password': ticket };
var anyUrl = sourceUrl.substring(0,sourceUrl.indexOf('/app/'+application));
var restApiUrl = anyUrl + '/rest/api/auth/login';
// We retrieve the authentication token
axios.post(restApiUrl, postData).then(function (response) {
if (response && response.data) {
if (response.data.is_authentication_error) {
alert("Your session has expired, please refresh your browser.");
return;
}
authBearer = {
headers: {
'Authorization': response.data.token_type + ' ' + response.data.access_token
}
};
- Ensuite, nous récupérons, pour chaque ID de document passé dans le paramètre de sélection, toutes ses métadonnées
//For each content ID we prepare the URL to retrieve contents
for (id of selection)
dumpUrls.push(anyUrl + '/rest/api/app/' + application + '/contents/' + id);
var requests = dumpUrls.map((url) => axios.get(url, authBearer));
//For each content ID sent as query parameters, we retrieve the metadata
axios.all(requests).then(function (responses) {
var geocodePromises = [];
for (var i = 0; i < responses.length; i++) {
var response = responses[i];
console.info(response);
if (response && response.data) {
var document = response.data.result[selection[i]];
if (document) {
//We retrieve the country and the city value
var sQuery = C6.getPropertyValue(document.metadata, cityMetadata) + ' ' + C6.getPropertyValue(document.metadata, countryMetadata);
//And based on those value, we retrieve the coordinates
geocodePromises.push(
mapboxClient.geocoding.forwardGeocode({
query: sQuery,
autocomplete: false,
limit: 1
}).send()
);
}
}
}
- Enfin, nous utilisons l'API mapbox pour localiser la ville et l'afficher sur la carte.
var features = [];
Promise.all(geocodePromises).then(function (responses) {
//For each coordinate, we add a marker on the map
for (var i = 0; i < responses.length; i++) {
var response = responses[i];
if (
!response ||
!response.body ||
!response.body.features ||
!response.body.features.length
) {
console.error('Invalid response:');
console.error(response);
return;
}
const feature = response.body.features[0];
if (i == 0) {
map = new mapboxgl.Map({
container: 'map',
// Choose from Mapbox's core styles, or make your own style with Mapbox Studio
style: 'mapbox://styles/mapbox/streets-v12',
center: feature.center,
zoom: 8
});
}
features.push(feature);
}
var bounds = new mapboxgl.LngLatBounds();
for (feature of features) {
new mapboxgl.Marker().setLngLat(feature.center).addTo(map);
bounds.extend(feature.geometry.coordinates);
}
if (responses.length > 1)
map.fitBounds(bounds, { padding: 100 });
});