Développement d'une Mailbox-centric App pour Office 2013

Publié dans: 

Les Mail Apps sont des applications destinées pour Outlook (client riche ou web). Par exemple, vous pouvez créer une application qui récupère les adresses (format US pour le moment) et les affiche sur bing map dans l’élément sélectionné. Le modèle de développement du Mail App est basé sur les règles d’activation. Les règles d’activation s’exécutent et sont vérifiées quand l’utilisateur sélectionne un élément.

Dans le contexte d’Outlook, les Mail Apps s’exécutent dans un processus isolé. Dans le contexte du web, ils sont isolés dans leurs propres iFrame

 

Quand une Mail App est activée pour un élément Outlook spécifique, son nom apparait dans une barre juste au-dessus du contenu de l’élément. L’utilisateur pourra lancer une Mail App en cliquant sur le nom de l’application, cette action chargera son contenu.

Plusieurs règles d’activation sont liées à un élément spécifique dans le contenu du mail (par exemple une adresse). Ce contenu est considéré comme un « context trigger » et sera surligné pour spécifier à l’utilisateur ce qu’utilise l’application lancée.

Hébergement :

L’infrastructure pour les Mails Apps requiert :

  • un Exchange 2013 et un serveur Exchange pour les boites de messagerie des utilisateurs et les manifest des applications installées. 

  • Un serveur Web pour contenir l’application elle-même (HTML, CSS, JavaScript, etc.).

Une Mail App peut utiliser l’EWS (Exchange Web Service) qui fournit la possibilité de créer et lire des éléments Outlook depuis la boite de réception de l’utilisateur courant.

Il existe deux manières de faire appel à ce Web service :

  • Directement depuis la Mail App : Cet appel peut se faire directement depuis un code JavaScript dans la Mail App.

  • Depuis le serveur Web : L’autre moyen serait de faire appel au serveur Web en lui passant les paramètres de sécurité nécessaire pour qu’il fasse appel à l’EWS. Cela permet à un code serveur écrit en C# ou VB.NET d'intéragir avec l'EWS.

Développement :

Comme les document-centric App, les Mail Apps sont développées avec Visual Studio 2012. Après le lancement de l’assistant de création d’une Mail App sur VS, vous devez :

  • Spécifier la hauteur de 32 à 350 pixels

  • Définir les règles d’activation

  • Création d’UI et les styles CSS

  • Ecrire code JavaScript pour la logique métier et les comportements.

  • Déboguer sur VS 2012 en ayant un Exchange server 2013 et un compte Exchange.

Règles d’activation :

Chaque Mail App est créée avec une ou plusieurs règles d’activation. Ces règles d’activation sont définies dans le fichier Manifest de l’application. A chaque sélection d’un élément Outlook par l’utilisateur, ces règles d’activation sont exécutées pour vérifier si les conditions sont remplies pour activer l’application et la rendre disponible pour que l'utilisateur la lance.

Une Mail App peut se baser sur une seule règle d’activation. Cependant, elle peut contenir plusieurs règles combinées pour un besoin d’activation compliqué. Vous pouvez combiner ces règles avec des AND et des OR.

Une règle d’activation peut se baser sur des entités connues comme l’adresse ou un numéro de téléphone. Pour des scénarios plus spécifiques, elle peut être définie avec des expressions régulières personnalisées.

Visual Studio 2012 fournit un éditeur de fichier Manifest, cependant il est parfois nécessaire de connaitre le code généré par l’assistant. Parmi les informations à connaitre, on cite les types de règle d’activation qui sont :

  • ItemIs : Vérifie le type de l’élément

  • ItemHasKnownEntity : Vérifie si l’élément sélectionné possède une entité connue

  • ItemHasRegularExpressionMatch : Définit une expression régulière à chercher dans le contenu de l’élément

  • RuleCollection : La combinaison des règles d’activation avec des AND et des OR

Voici la liste des Entités connues par Outlook 2013 :

  • Address : Adresse format USA

  • EmailAddress: Adresse mail

  • MeetingSuggestion : référence à un événement ou réunion

  • Contact : Un nom relié à d’autres entités

  • PhoneNumber : Numéro de téléphone format USA

  • TaskSuggestion : une phrase d’action dans l’email

  • Url : Nom de fichier ou adresse web

Ci-dessous un exemple d'un code XML des règles d'activation dans le fichier Manifest de l'application:

 <Rule xsi:type="RuleCollection" Mode="And">
    <Rule xsi:type="RuleCollection" Mode="Or">
      <Rule xsi:type="ItemIs" ItemType="Message" />
      <Rule xsi:type="ItemIs" ItemType="Appointment" />
    </Rule>
    <Rule xsi:type="RuleCollection" Mode="Or">
      <Rule xsi:type="ItemHasKnownEntity" EntityType="Contact" RegExFilter="ID" FilterName="state" IgnoreCase="false" />
      <Rule xsi:type="ItemHasKnownEntity" EntityType="Url" />
      <Rule xsi:type="ItemHasRegularExpressionMatch"
      PropertyName="BodyAsHTML" IgnoreCase="true"
      RegExName="Invoices"
      RegExValue="\bINVOICE#\s*([0-9][0-9][0-9][0-9][0-9][0-9])+\b"/>
    </Rule>
  </Rule>

Outlook JSOM

 

L’accès au Modèle d’objet JavaScript d’Outlook se fait à partir de l’objet Office.context.mailbox.

Depuis cet objet vous pouvez accéder aux informations de l’élément Outlook sélectionné et du profile de l’utilisateur courant ou des autres utilisateurs comme celui qui a envoyé le mail.

L’Outlook JSOM fournit un accès aux propriétés de l’élément comme :

  • le contenu, objet ou date d’envoi du message courant.

  • Date et heure de début et fin pour les rendez-vous en réunion

  • Accès aux entités connues et aux expressions régulières.

  • Si la Mail App possède les permissions approprié, le code de l’application pourra faire des appels aux EWS pour créer et/ou récupérer des éléments Outlook.

  • Création d’un jeton single sign-on pour les appels EWS.

Exemple :

Accès aux propriétés d'un élément

Office.initialize = function () {
	var item = Office.context.mailbox.item;
     	$('#subject').text(item.normalizedSubject);
	$('#from').text(item.from.displayName);

 

Accès au profile utilisateur

Office.initialize = function () {
	var userProfile = Office.context.mailbox.userProfile;
        	$('#displayName').text(userProfile.displayName);
        	$('#timeZone').text(userProfile.timeZone);

Regex matches 

var myInvoices = item.getRegExMatches();
myString = "";
for (var i in myInvoices.Invoices) {
	myString += myInvoices.Invoices[i] + ", ";
}
$('#regexInvoices').text(myString);

Accès aux entités extraites

var myEntities = item.getEntities();
var myUrls = myEntities.urls;
var myString = "";
for (i = 0; i < myUrls.length; i++) {
	myString += "<a href='" + myUrls[i] + "'>" + myUrls[i] + "</a>" + " <br />";
}

L’objet JSOM permet la sauvegarde de propriétés personnalisées pour un élément Outlook puis les retrouver afin d’implémenter une logique métier. La valeur des propriétés personnalisées est associée à un seul élément. L’exemple le plus courant est le faite de récupérer les valeurs des propriétés personnalisées lors du lancement de l’application qui ont été sauvegardées.

Ci-dessous un exemple de code 

Office.initialize = function () {
	var outlook = Office.context.mailbox;
	Outlook.item.loadCustomPropertiesAsync(customPropsCallback)
}

function customPropsCallback(asyncResult) {
	var customProps = asyncResult.value;
	var myProp = customProps.get(“myProp”);
	customProps.set(“otherProp”, “value”);
	customProps.saveAsync(saveCallback);
}

function saveCallback(asyncResult) {
}

Permissions 

Niveau de sécurité :

Chaque Mail App est définie avec les paramètres de permission dans fichier Manifest qui détermine le niveau de permission requit par les utilisateurs et les administrateurs.

Ci-dessous les différents niveaux de permission :

  • Restricted : C’est le niveau minimal. Il permet la lecture des entités connues mais ne permet pas la lecture du contenu de l’élément Outlook sélectionné et ne peut pas utiliser les expressions régulières dans les règles d’activation. Il permet un accès partiel au JSOM et pas d’accès au EWS.

  • Read Item : Ce niveau de permission inclut les permissions du niveau Restricted plus d’autres privilèges comme la lecture du contenu du mail, la possibilité d’utiliser les expressions régulières et un accès total au JSOM.

  • Read/Write MailBox : C’est le niveau maximal de permission. Les Mail Apps avec ce type de permission ne peuvent être installées que par l’administrateur du serveur Exchange parce qu’ils ont accès au EWS qui rend possible la création, lecture, écriture, envoie de mail et permet aussi la gestion des dossiers.

Single Sign-on API :

Le JSOM permet aux Mail Apps qui ont le niveau de permission Read/Write MailBox de faire des appels au EWS. Pour pouvoir effectuer cette opération, vous devez récupérer le token de l’utilisateur courant qui contient certaines informations comme

  • L’UPN (User Principal Name),

  • Adresse SMTP

  • Identifiant unique qu’Exchange s’en sert dans partie serveur pour relier le token à l’identifiant de l’utilisateur.

Office.initialize = function () {
	Office.context.mailbox.getUserIdentityTokenAsync(tokenCallback)
}

function tokenCallback (asyncResult) {
	token = asyncResult.value;
}

Recommandations :

Affichage

Les Mail Apps doivent respecter certaines recommandations, ci-dessous quelques-unes  :

  • Hauteur entre 32 et 350 pixels

  • Pas de contrôle sur la largeur

  • Les Scrollbars doivent être évités, vous pouvez explicitement le cacher en appliquant le style overflow :hidden sur le body

Il existe trois types de paramétrage dans le fichier Manfest

  • Default Setting 

  • Tablet Settings pour les tablette

  • Mobile Settings pour les smartphone

Cela vous permet de définir la page de démarrage (donc fichiers de style et scripts différents) et la hauteur pour chaque environnement.

Performance

Quand vous créez une Mail App, vous devez prendre en considération la performance dans vos développements.

Vous devez noter que :

  • Le client de bureau d'Outlook applique les limites d'utilisation des ressources et il désactivera automatiquement les Mail Apps qu'il trouve consommatrices en ressources.

  • Les seuils de performance peuvent être réglés par les administrateurs. 

  • Les metrics vérifient les caractéristiques de performance telles que le traitement de l'évaluation Regex, l'utilisation du processeur, utilisation de la mémoire, et la stabilité.

Liens Utiles

Ci-dessous d'autres articles liés :

Intoduction des application pour Office 2013

Développement d'une Document-Centric App pour Office 2013