Très pratique pour démarrer rapidement une machine virtuelle sur Windows Server 2012 Datacenter, avec les prérequis et les binaires de SharePoint Server 2016 Preview.

Bien suivre les recommandations de sizing (A4 minimum) :

Les liens importants

Si vous souhaitez la télécharger, vous pouvez suivre les liens suivants :

https://www.microsoft.com/en-us/download/details.aspx?id=48712

Voici quelques autres liens importants à connaître :

SharePoint Server 2016 IT Preview Quick Start Guide:
http://www.microsoft.com/en-us/download/details.aspx?id=48714

SharePoint Server 2016 IT Preview Reviewer Guide
http://www.microsoft.com/en-us/download/details.aspx?id=48713

SharePoint Server 2016 IT Preview Datasheet
http://www.microsoft.com/en-us/download/details.aspx?id=48715

La documentation technique (Technet):
https://technet.microsoft.com/en-us/library/cc303422(v=office.16).aspx

Les nouveautés fonctionnelles

Chers amis francophones, voici une présentation (non exhaustive) en français de quelques nouveautés fonctionnelles (et uniquement elles) apportées par cette version. Vous pourrez retrouver dans de futurs billets les nouveautés techniques (pour les IT Pro).

Si, en plus de SharePoint Server, vous êtes utilisateur de SharePoint Online, peut être connaisez vous déjà certaines des nouveautés fonctionnelles apportées par cette nouvelle version. En effet, il est bon de rappeler que depuis la version 2013, les équipes produit SharePoint travaillent d'abord sur la version Online de SharePoint, puis reversent progressivement les nouveautés vers SharePoint Server. Dernier conseil : même en tant que fan de SharePoint Server, il est impératif à mon sens aujourd'hui de bien connaître SharePoint Online qui bouge rapidement et est plus riche de jour en jour.

La barre de navigation, appelée désormais "Apps Launcher"

Finit la "barre bleue" en haut par défaut avec le mot SharePoint à gauche et à droite les liens vers OneDrive, Newfeed/Yammer et Sites. Désormais, SharePoint Server 2016 reprend le look and feel d'Office 365 pour présenter un accès sous forme de "lanceur applicatif" aux différentes applications. En haut à droite on retrouve la photo de profil de l'utilisateur, ainsi qu'un lien vers les Apps mises en avant par l'administrateur.

Bien plus conforme au visuel d'Office 365, et donc plus facile pour faire de la coexistence de services entre SharePoint Server et SharePoint Online.

Prévisualisation des images et des vidéos dans les bibliothèques de document

Avec SharePoint Server 2013 ou avant, la prévisualisation des médias types images et vidéos, depuis une bibliothèque de document, pouvait sembler un peu "rustique", dans le sens où lorsque l'on cliquait sur l'image ou la vidéo, on ouvrait directement le fichier comme une nouvelle page. Sur les sites web, il est souvent préférable d'utiliser un système dit de type "LightBox" (du nom de la 1iere librairie Javascript qui permettait l'implémentation de ce système). C'est maintenant chose faite, SharePoint Server 2016 intègre cette prévisualisation des fichiers sous forme de "popin", c'est-à-dire une nouvelle fenêtre en surimpression qui permet de garder la navigation en cours sans ouvrir une nouvelle page.

Nouvelle expérience de navigation en mobilité

SharePoint Server 2013 apportait un bon nombre de nouveautés concernant l'expérience de navigation en mobilité, comme par exemple les "devices channels". Toutefois ces nouveautés concernaient quasiment exclusivement les sites de publication. Les sites collaboratifs avaient également vues une mise à jour de l'expérience mobile, mais celle-ci restait assez sommaire et simple, et relativement proche de cette fonctionnalité introduite en 2010. Les fonctionnalités étaient assez réduites et il était plutôt complexe de repasser sur une vue PC (ou dite de navigateur classique) pour aller plus loin.

Maintenant, l'expérience en mobilité des sites collaboratives est bien meilleure, et surtout orientée pour une expérience dite "touch". Vous pouvez retrouver un très bon post de blog de présentation de cette fonctionnalité lors de sa sortie sur SharePoint Online ici.

Amélioration de la gestion des fichiers (taille maximale, caractères spéciaux, liens durables, etc.)

Avec SharePoint Server 2013, la taille maximale d'un fichier était d'environ 2 Go. C'est maintenant chose révolue et vous pouvez déposer ou télécharger des fichiers bien plus volumineux. A noter qu'une nouveau paramétrage permet à l'administrateur de la ferme SharePoint de choisir, par web application, la limite maximale de la taille de fichiers désirée.

Autre nouveauté intéressante du côté du nommage des fichiers. Avec la version 2013 (et les versions précédentes), il était impossible de créer un fichier plus long que 128 caractères et qui contenant les caractères spéciaux du type &, ~, {, ou }. C'est désormais terminé, c'est maintenant possible avec la version 2016.

Améliorations de l'interface et de l'accessibilité des bibliothèques de documents

Les bibliothèques de documents connaissent un léger lifting, avec une barre d'outils légèrement plus claire :

On va surtout retrouver de nombreuses nouveautés concernant l'accessibilité de ces bibliothèques de documents, avec la gestion du focus ou encore la gestion des raccourcis clavier. On peut par exemple maintenant faire certaines opérations avec des combinaisons de touches, comme par exemple :

• ALT+N : création un nouveau fichier ou répertoire
• ALT+E : pour éditer
• ALT+U : uploader un fichier
• ALT+M : Manager
• ALT+S : Partager (Share)

Améliorations de la fonctionnalité de partage

La fonctionnalité de partage a été une bonne nouveauté de la version 2013, permettant à tout utilisateur sans connaissance SharePoint de facilement partagé un fichier ou l'accès à un site. Suite aux retours des utilisateurs le groupe produit a apporté un bon nombre de nouveauté pour encore améliorer ce principe.

Une fonctionnalité que je trouve intéressante par exemple est la possibilité désormais de partager un répertoire en même temps que sa création. C'est un cas d'usage courant pour les utilisateurs finaux et cela aide à aller plus vite. Voici un exemple de la séquence de clics :

Il y'a évidemment bien d'autres amélioration, comme par exemple le mail d'invitation, ou encore les liens durables, l'approbation d'une invitation directement par mail, etc.

Le "pin" de sites

Dans la liste des sites que vous suivez, vous pouvez maintenant "piner" (on va dire que ça se dit ;-)) un site pour le faire apparaître en début de liste. Plus pratique pour s'y retrouver lorsque l'on suit un grand nombre de sites : 

Amélioration de OneDrive for Business (aka OneDrive Entreprise)

Une nouveauté très attendue est bien sûr l'évolution de OneDrive for Business, tant les différences entre SharePoint Online et SharePoint Server 2013 étaient devenues importantes. Dans cette nouvelle version, on va retrouver un certaines nombres de nouveautés majeures.

Par exemple, nous avons désormais un nouveau look and feel pour provisionner son site lors de la 1iere connexion. L'ergonomie est meilleure et surtout le processus de création du site est bien plus rapide. Ceci est d'ailleurs vrai pour tous les modèles de sites, grâce à une nouvelle fonctionnalité introduite, qui fait en sorte que désormais les sites ne sont plus systématiquement recréés "from scratch", mais "instanciés" depuis des modèles cachés.

Voici quelques captures d'écran du nouveau processus de création d'un nouvel espace OneDrive for Business :

 L'ergonomie des sites OneDrive a été largement revue, permettant une prise en main plus simple de l'interface. On a par exemple :

• La suppression du ruban, très utile pour les experts SharePoint et les bibliothèques de documents, moins pour OneDrive et des utilisateurs néophytes
• Le nouveau look and feel des bibliothèques de documents
• La nouvelle barre de recherche avec auto complétion à gauche
• Le nouvel écran "Site Folders" vous permettant de retrouver facilement les sites ou bibliothèques que vous suivez
• Les fonctionnalités de partages qui ont été améliorées

Capture d'écran de la nouvelle interface de OneDrive for Business :

Capture d'écran de "Site Folders" :

Fonctionnalités de gestion de la conformité et de protection numérique 

Sur le sujet de la compliance et de la gouvernance de contenu en général, on va retrouver un grand nombre de nouveautés, comme c'est déjà le cas dans Office 365.

Désormais, deux nouveaux modèles de sites sont disponibles, permettant à des équipes de "monitorer" le contenu partagé sur SharePoint et établir des règles de ce que peuvent faire ou non les utilisateurs par espace :

• Le modèle dit "Compliance Policy Center": vous permet de gérer un cycle de vie à vos données de façon centralisée
• Le modèle dit "In-Place Hold Policy Center" : vous permet d'identifier des types de données pour les verrouiller. On retrouve par exemple des modèles de données à détecter, comme par exemple des cartes de crédits, etc. Pratique également pour se prémunir de la fuite potentielle d'information (aka DLP).

 Quelques captures du Compliance Policy Center : 

 Quelques captures du "In-place Policy center" :

Conclusion

Voilà quelques nouveautés de SharePoint Server 2016 Preview de la release du 24 Août, même si c'est qu'un rapide et succinct aperçu. Ce billet n'est pas exhaustif sur les nouveautés, Rendez-vous dans un prochain billet pour plus d'aventures.

Et voilà, le très attendu SharePoint Server 2016 est bientôt parmi nous. En attendant la version finale prévue pour le printemps 2016, depuis le 24 Août Microsoft a mis à disposition la version Preview. Cette version est une version "beta" publique qui peut être essayée gratuitement pendant 180 jours.

Voici une procédure en français pour vous aider à installer et essayer cette version avec des captures d'écran à chaque étape. Avertissement : ceci est une installation "stand alone", c'est-à-dire que tous les rôles SharePoint sont installés sur une seule et même machine (aka Single Server Farm). Ce n'est évidemment pas une bonne pratique pour une ferme de production, mais ceci fait l'affaire pour une machine de développement ou d'intégration. Pour finir, si vous souhaitez avoir un peu plus d'information sur cette nouvelle version de SharePoint, ainsi que connaître les limitations et le rôle de la version Preview, je vous conseille les deux articles suivant (en anglais) : https://blogs.office.com/2015/08/24/announcing-availability-of-sharepoint-server-2016-it-preview-and-cloud-hybrid-search/ (annonce officielle) et http://www.learningsharepoint.com/2015/08/24/things-you-need-to-know-before-you-install-sharepoint-2016-preview/

Téléchargement des binaires et prérequis

Avant de se lancer dans l'installation, il nous faut impérativement deux choses: télécharger les binaires d'installation et préparer la machine virtuelle.

Pour télécharger les binaires d'installation, rendez-vous à l'adresse suivante : https://www.microsoft.com/en-us/download/details.aspx?id=48712

N'y chercher pas la version française ou un language pack français, la version Preview de SharePoint 2016 n'est disponible à ce stade qu'en anglais ou avec les languages packs Japonais et Espagnol. Noter également dans ce lien en dessous la clé produit, elle vous sera nécessaire pendant l'installation.

Deuxième étape, la préparation de la machine virtuelle qui hébergera notre serveur. Au niveau des performances de la machine, n'hésitez pas à être généreux. Si vous utilisez Microsoft Azure (vivement recommandé), je vous conseille par exemple d'opter pour une machine de type A6 ou plus. En gros, optez pour une machine du type :

16 Go RAM minimum (prévoir même plutôt 24 Go), 64-bit, Processeurs 4 cores à + de 2Ghz, 80 Go pour le disque système, un disque secondaire de 100 Go ou plus. 

Au niveau de la version du système d'exploitation et de la base de données, je vous conseille : L'édition 64-bit de Windows Server 2012 R2 Standard ou Datacenter et au niveau de SQL Server vous pouvez opter pour l'édition 64-bit de Microsoft SQL Server 2014 Service Pack 1 (SP1) ou l'édition 64-bit de Windows Server 2012 R2 Standard ou Datacenter.

N'oubliez pas également de créer un contrôleur de domaine Active Directory et de créer les comptes adéquat à une installation de SharePoint (vous pouvez vous référer au guide de 2013 pour cela, les choses n'ont guère évoluées à ce niveau : https://technet.microsoft.com/en-us/library/cc678863.aspx). Activer sur ce serveur les rôles Web Server (IIS) et Application Server (framework .net etc.).

Comme vous allez le voir, d'autres prérequis sont nécessaires pour installer SharePoint Server. Toutefois, l'outil d'installation est capable de les télécharger et les installer pour vous. Cela suppose toutefois que votre serveur puisse se connecter à Internet. Si ce n'est pas le cas, voici la liste complète des prérequis nécessaires à l'installation :

• Web Server (IIS) role
• Application Server role
• Microsoft .NET Framework version 4.5.2
• Microsoft SQL Server 2012 Native Client
• Microsoft WCF Data Services 5.6
• Microsoft Information Protection and Control Client (MSIPC)
• Microsoft Sync Framework Runtime v1.0 SP1 (x64)
• Windows Management Framework 3.0 which includes Windows PowerShell 3.0
• Microsoft Identity Extensions
• Windows Server AppFabric 1.1
• Cumulative Update Package 1 for Microsoft AppFabric 1.1 for Windows Server (KB 2671763)
• Microsoft ODBC Driver 11 for SQL Server
• Update for Microsoft .NET Framework to disable RC4 in Transport Layer Security (KB2898850)
• Visual C++ Redistributable Package for Visual Studio 2013 

Dernier conseil et pas des moindre, installer tous ces logiciels en version anglaise EN-US !! Cela vous évitera probablement bien des ennuis sur des scénarios non encore testés par le groupe produit !! 

Installation des binaires

Ca y'est vous êtes prêt à lancer l'installation ? C'est partit !

Faites cette installation avec un compte d'installation qiu possède les droits administrateurs de la machine.

Tout d'abord, faite un clic droit sur l'image ISO et cliquer sur Mount :

 Cela vous ajoutera un lecteur qui porte le numéro de release de la version Preview (16.0.4316.1217). Ouvrez ce lecteur :

 Lancer l'exécutable prerequisiteinstaller.exe qui est l'outil pour installer les prérequis : 

Cliquer sur Next :

L'outil va configurer les rôles nécessaires sur le serveur :

Cliquer sur Finish, le système va redémarrer :

Après le redémarrage, l'outil de prérequis va reprendre l'installation. Si ce n'est pas le cas, remonter l'image iso et relancer l'outil d'installation des prérequis, cela va reprendre aux installations suivantes. Cocher "I accept.." et cliquer sur Next :

Tous les prérequis vont être installés. Une fois terminé cliquer sur Finish, puis le système va encore une fois redémarrer :

Une fois redémarré, lancer l'exécutable nommé setup.exe pour lancer l'installation :

Patientez durant la vérification des prérequis. Ne vous inquiétez pas si la fenêtre semble "frisée" et attendre que celle-ci vous redonne la main : 

Si les prérequis sont bien installés, vous allez être inviter à saisir la clé du produit. Pour la version Preview, la clé est disponible juste en dessous du lien pour télécharger l'image ISO sur la page de Microsoft.com (voir adresse dans l'introduction). Cliquer ensuite sur Continue :

Cochez "I accept..", puis cliquer sur Continue :

Choisir les répertoire d'installation ou laisser par défaut, puis cliquer sur "Install Now" :

Patientez durant l'installation :

L'installation est terminée et vous allez être invité à lancer le "Configuration Wizard" qui va vous permettre de créer et configurer votre ferme SharePoint 2016 :

Configuration de la ferme (aka Config Wizard)

Si vous avez laissé cocher "Run the..", l'écran suivant va se lancer automatiquement. Si ce n'est pas le cas, ce n'est pas un soucis, vous retrouverez ce programme dans votre liste d'applications sous le titre "SharePoint Products Configuration Wizard". Cliquez sur Next : 

Le programme a besoin de redémarrer IIS, cliquer sur Yes :

Nous allons créer un nouvelle ferme, donc cocher "Create a new server farm" et cliquer sur Next :

Saisir le nom de votre instance SQL, ainsi que le compte et le mot de passe du compte d'accès (exemple: le compte administrateur de ferme). Cliquer sur Next : 

Saisir une "passphrase" (mot de passe par exemple). Celui-ci est important, conserver le de côté. Il vous sera nécessaire si vous décider de rajouter un nouveau serveur dans votre ferme plus tard. Cliquer sur Next :

C'est la grande nouveauté de la version 2016 : la capacité d'installer configurer votre serveur à partir de modèles topologiques. On peut choisir par exemple un serveur web frontal, un serveur pure applicatif, etc. etc. Pour une ferme mono-machine "all-in-one", cocher "Single Farm Server" et cliquer sur Next :

Choisir le port de votre centrale d'administration (site de gestion de la ferme) et choisir le mode d'authentification (par défaut choisir NTLM). Cliquer sur Next :

SharePoint vous récapitule les informations, si elles sont correctes, cliquer sur Next : 

Patientez durant la configuration (l'étape 3 - création et configuration des bases de données va prendre un peu de temps ne pas s'en inquiéter) :

Si tout s'est bien passé, l'écran suivant va apparaître, cliquer sur Finish :

Configuration additionnelle dans la centrale d'administration

Félicitations, le plus gros de l'installation est derrière nous. Maintenant nous allons finir les étages de configuration qui se font via la centrale d'administration. Cette fenêtre va normalement s'ouvrir toute seule. Si ce n'est pas le cas pas de panique, vous pouvez retrouver un lien dans votre menu d'application (ex menu démarrer) ou y accéder par votre navigateur via le port choisit précédemment.

Au 1ier lancement, SharePoint va vous proposer de reporter vos erreurs aux équipes produit pour permettre d'améliorer la version 2016 d'ici sa sortie. Cocher "Yes.." et cliquer sur OK :

Vous aller maintenant être invité à configurer les services techniques de SharePoint. Deux choix sont possibles : utiliser l'assistant (Wizard) ou le faire manuellement. Les puristes et les installations de production préférerons évidemment une installation à la main. Pour un environnement de test, le wizard fait très bien l'affaire. Cliquer sur le bouton "Start the Wizard" :

L'assistant va vous inviter à choisir les comptes et services à utiliser dans votre ferme. Saisir le compte et le mot de passe du compte de service à utiliser puis cocher les services que vous souhaitez utiliser :

Cochez les services que vous souhaitez utiliser. Noter que j'ai ici cocher le service "Microsoft SharePoint Insights", car celui-ci est une nouveauté de SharePoint 2016 et que je suis intéressé par le tester ;-) Cliquer sur Next :

La configuration des services va commencer, ne pas s'étonner si cette étape prend du temps, il y'a pas mal de boulot sous-jacent. Prenez votre mal en patience ;-)

Félicitations ! Votre configuration est terminée ! SharePoint est maintenant prêt à être utilisé ! Vous pouvez noter l'apparition de "l'App Launcher" en haut à gauche du ruban noir supérieur.

Création d'un site d'équipe

L'installation à proprement parlé est terminée. Toutefois pour tester un site SharePoint, il nous reste à créer un site d'équipe.

Pour cela, cliquer sur "Manage Web applications":

 Normalement une web application nommée "SharePoint - 80" a été créé et est disponible sur le port 80. Vérifiez que c'est bien le cas et revenez en arrière :

Cliquez sur "Create site collections" : 

Saisir le nom de votre site (par exemple ici "Team Site") :

Choisir un modèle de site (par exemple le "team site"), puis saisir le compte du propriétaire du site :

Cliquer sur OK :

Le processus de création du site est en cours :

La création est terminée, cliquer sur l'adresse de votre site :

Un nouvel onglet apparaît et vous donne accès à votre site d'équipe :

Conclusion

Bravo, vous avez terminé ! Votre ferme SharePoint Server 2016 Preview est maintenant opérationnelle et vous allez pouvoir vous amuser avec d'ici la sortie de la version finale.

Comme vous avez pu le constater si vous connaissez la version 2013 de SharePoint Server, l'installation n'est pas très différente et vous retrouverez facilement vos marques. A noter tout de même l'installation de serveurs avec des rôles spécifiques, qui aide grandement la construction de ferme SharePoint multiserveurs.

Cette nouvelle fonctionnalité est appelée "Min Roles", et est une nouveauté importante pour les IT Pro. Nous aurons l'occasion d'en reparler dans de futurs articles.

Enjoy SharePoint Server 2016 Preview !

Voici les présentations que j'ai co-animé :

SharePoint on premises et Yammer, quels usages et quelle intégration ? 

Avec Guelnoji Njetein (MCS) et Kevin TRELOHAN (MVP) :

L'Office Graph et le futur des modes travail

Avec Alexandre Cipriani (MS) et Stéphane Palluet (MS) 

Office Vidéo : le streaming vidéo pour entreprise prêt à l’emploi 

Avec Alexandre Cipriani (MS) et Stéphane Palluet (MS)  

Key Resources for Delve

-       Announcing Delve  [Blog]

-       What is Office Delve? 

-       Introducing Office Delve  [Video]

-       Powered by Office Graph  [Video]

-       How to turn on First Release 

-       Who can see my documents in Office Delve?  

Office Delve for Office 365 admins

https://support.office.com/Article/Delve-for-Office-365-admins-54f87a42-15a4-44b4-9df0-d36287d9531b

Using GQL with the SharePoint Online Search REST API to query Office graph

http://msdn.microsoft.com/en-us/library/office/dn783218(v=office.15).aspx

Matériel End-User et Admin Office 365 en Français :

Office Delve pour les administrateurs Office 365

https://support.office.com/fr-fr/article/Office-Delve-pour-les-administrateurs-Office-365-54f87a42-15a4-44b4-9df0-d36287d9531b?ui=fr-FR&rs=fr-FR&ad=FR

Qu’est-ce qu’Office Delve ?

https://support.office.com/fr-fr/article/Quest-ce-quOffice-Delve--1315665A-C6AF-4409-A28D-49F8916878CA?ui=fr-FR&rs=fr-FR&ad=FR

Comment Office Delve détermine-t-il ce qui est pertinent pour moi ?

https://support.office.com/fr-fr/article/Comment-Office-Delve-d%C3%A9termine-t-il-ce-qui-est-pertinent-pour-moi--048D502E-80A7-4F77-AC5C-F9D81733C385?ui=fr-FR&rs=fr-FR&ad=FR

Regrouper et partager des documents dans Office Delve

https://support.office.com/fr-fr/article/Regrouper-et-partager-des-documents-dans-Office-Delve-DA0C5804-01EF-4EDD-8B87-E576B19BEF3E?ui=fr-FR&rs=fr-FR&ad=FR

Raccourcis clavier pour Office Delve

https://support.office.com/fr-fr/article/Raccourcis-clavier-pour-Office-Delve-6d4ca665-6d65-4aa4-a311-136937eeb33f?ui=fr-FR&rs=fr-FR&ad=FR

Utiliser les cartes de contenu dans Office Delve

https://support.office.com/fr-fr/article/Utiliser-les-cartes-de-contenu-dans-Office-Delve-E6157225-0E40-441C-906F-0C82BFEE55F3?ui=fr-FR&rs=fr-FR&ad=FR

Donner de l’importance à votre contenu dans Office Delve

https://support.office.com/fr-fr/article/Donner-de-limportance-%C3%A0-votre-contenu-dans-Office-Delve-50D22F53-56E7-4D0E-9D8E-978BD9A3040D?ui=fr-FR&rs=fr-FR&ad=FR

Stocker vos documents dans un emplacement accessible par Office Delve

https://support.office.com/fr-fr/article/Stocker-vos-documents-dans-un-emplacement-accessible-par-Office-Delve-49a0db49-5e6c-4dda-816e-e11dd77de49d?ui=fr-FR&rs=fr-FR&ad=FR

Quel type d’informations puis-je trouver dans Office Delve ?

https://support.office.com/fr-fr/article/Quel-type-dinformations-puis-je-trouver-dans-Office-Delve--46f92806-b52c-4187-b60e-b3bf8d25f73e?ui=fr-FR&rs=fr-FR&ad=FR

Mes documents sont-ils en sécurité dans Office Delve ?

https://support.office.com/fr-fr/article/Mes-documents-sont-ils-en-s%C3%A9curit%C3%A9-dans-Office-Delve--f5f409a2-37ed-4452-8f61-681e5e1836f3?omkt=fr-fr&ui=fr-FR&rs=fr-FR&ad=FR#

1. Introduction

Si vous êtes intéressé par le développement d’Apps pour mobiles, vous devez sans-doute connaître Apache Cordova. Apache Cordova permet de créer simplement des applications pouvant être déployées, avec un même code, sur des appareils mobiles différents : iOS (iPhone et iPad sous iOS 6, 7 ou 8), Androïd (2.3.3 ou +), Windows Phone 8 ou pour Apps universelles Windows 8.1 (Windows Phone ou Windows 8.1). On appelle couramment ce type d’Apps des « Apps hybrides ». Cordova est aujourd’hui très populaire et est utilisée par de très nombreuses applications grand public.

Cordova offre quelques avantages notables pour la création d’Apps Mobiles, comme :

• L’utilisation d’un seul et même code pour tous les types de périphériques
• L’utilisation de technologies web (HTML 5, CSS, JavaScript), rapide à développer et bien connues
• Ne nécessite pas une connaissance pointue des spécificités de développement de chaque plateforme

Aujourd’hui on peut tirer parti pleinement des capacités de Cordova dans le monde entreprise, et en particulier avec les plateformes Microsoft dans le cloud et Office 365.

Il est par exemple très simple de développer des applications capables de se connecter de façon sécurisée à Office 365 (et donc également à SharePoint Online). On peut proposer aux utilisateurs une vraie immersion du monde professionnel au sein de leur téléphone professionnel ou personnel.

Dans cet article, nous allons regarder comment réaliser une application mobile capable de se connecter à SharePoint Online pour remonter le contenu d’une liste d’actualité ou les derniers éléments d’une bibliothèque de documents.

NOTE : Vous pouvez télécharger le code source d’exemple de cette application en bas de cet article.

2. Les technologies et outils à connaître et installer

Dans ce chapitre, nous allons utiliser quelques briques importantes à connaître pour réaliser rapidement et efficacement une App Mobile.

2.1 Le moteur d’exécution et l’éditeur de code

Pour développer une App de ce type, il nous faut un certain nombre d’éléments installés.

Voici une liste des éléments qu’il vous faudra installer :

1. Visual Studio 2013 avec les fonctionnalités "Tools for Maintaining Store apps for Windows 8" and "Windows Phone 8.0 SDK". Je vous conseille d’utiliser plutôt les versions Pro, Premium ou Ultimate de Visual Studio, mais vous pouvez également utiliser la version Express gratuite « Visual Studio Express 2013 with Update 4 for Windows »  disponible en téléchargement ici : https://www.visualstudio.com/en-us/downloads/download-visual-studio-vs.aspx
2. L’update 4 de Visual Studio 2013, que vous pouvez télécharger ici : http://www.microsoft.com/fr-fr/download/details.aspx?id=44921 
3. Visual Studio Tools for Apache Cordova CTP3.1, que vous pouvez télécharger ici : http://www.microsoft.com/en-us/download/details.aspx?id=42675

Il existe un excellent guide sur MSDN pour vous aider dans l’installation des VS Tools pour Cordova : https://msdn.microsoft.com/en-us/library/dn771545.aspx

A noter que vous n’avez pas besoin d’installer Apache Cordova indépendamment, car les Tools pour Cordova vont réaliser un certain nombre de téléchargements et d’installation pour vous, pour vous permettre de débuguer et tester vos Apps sur Androïd par exemple.

Parmi eux, on peut noter :

• Joyent Node.js
• Git CLI
• Google Chrome
• Apache Ant
• Oracle Java JDK 7
• Android SDK
• SQLLite for Windows Runtime
• Apple iTunes

Dernier conseil (important) : si vous possédez un téléphone Windows Phone et que vous souhaitez déployer et tester votre App sur votre téléphone, il vous faut le « débloquer » en l’enregistrant en tant que téléphone de développement. La procédure est simple une fois que vous avez installé Visual Studio (qui contient le Windows Phone SDK), il vous suffit de suivre la procédure documentée ici :

https://msdn.microsoft.com/en-us/library/windows/apps/ff769508(v=vs.105).aspx

2.2 La couche de communication avec Office 365 et SharePoint Online

Microsoft a publié des aides au développement spécialement pour Office 365, appelées « Office 365 API ». Ce kit de développement permet de facilement créer des applications capables de s’interconnecter avec la plateforme Office 365. Avec ce SDK on peut réaliser un grand nombre d’actions sans pour autant être expert des différents composants d’Office 365.

On va pouvoir réaliser des opérations du type :

• Authentification et connexion de façon sécurisée ;
• Gestion des utilisateurs et des groupes d’Azure Active Directory ;
• Manipulation des données de messageries (mails, calendrier au sein d’Exchange Online) ;
• Manipulation des fichiers au sein de son OneDrive ou de sites SharePoint Online.

Dès sa sortie, ce kit de développement a été rendu disponible à la fois pour .Net, mais aussi pour Cordova, Xamarin ou les SDK natives d’Androïd et iOS.

Pour utiliser le SDK Office 365, vous devez télécharger et installer les « Office Developer Tools for Visual Studio 2013 », disponible depuis ce lien :

https://aka.ms/officedevtoolsforvs2013

2.3 La couche de rendu graphique

Maintenant que vous avez installé les outils de développement et l’extension Visual Studio pour Office 365, il ne nous reste plus qu’à choisir un framework graphique et JavaScript qui va nous aider à développer une interface graphique adaptée aux mobiles.

Il existe un certain nombre de frameworks HTML 5 populaires qui permettent de réaliser simplement des interfaces de ce type, parmi eux on peut citer :

• OnsenUI : Très beau framework qui se couple très bien avec AngularJS. OnsenUI présente un grand intérêt lorsque l’on souhaite réaliser une interface qui répond au basique des composants visuels pour iPhone ou Android. Seul bémol, il ne vaut mieux pas l’utiliser avec du JQuery, mais on peut facilement s’en passer. Plus d’information sur OnsenUI ici : http://onsen.io/
• JQuery Mobile : Un kit HTML 5 pour faire des contrôles et interfaces orientés mobilité.  Pour une App mobile on ne retrouve pas forcément les éléments d’interface propre au monde de la téléphonie.
• WinJS : Il s’agit d’un framework made-in-Microsoft pour réaliser simplement des interfaces en JavaScript avec le look-and-feel des interfaces Windows Modern UI et Windows Phone. WinJS peut être utilisé avec Angular ou non. Pour plus d’information sur WinJS, ça se passe ici : https://dev.windows.com/en-us/develop/winjs ou http://try.buildwinjs.com/

Dans cet exemple, nous allons utiliser WinJS pour notre couche graphique.

 3. Création d’un nouveau projet

3.1 Création du projet Cordova avec Visual Studio

Ouvrez Visual Studio 2013, cliquez sur « New » puis « Project ».

Dans la liste des templates à gauche, sélectionnez la partie JavaScript, puis la section « Apache Cordova Apps ». Sélectionner « Blank App », indiquer le nom de l’App ainsi qu’un chemin sur votre disque dur, puis cliquez sur « OK ».

Une fois créée, votre solution contient les fichiers HTML, JS et CSS de base vous permettant de commencer le développement orienté Web : 

Le fichier config.XML vous permet de modifier la plupart des paramètres de l’Application (comme son nom, l’éditeur, etc.) communs à toutes les plateformes, les plugins Cordova que vous souhaitez utiliser, ainsi que les paramétrages propres à chaque plateforme :

Pour exécuter et tester votre App, vous pouvez utiliser directement le lanceur de Visual Studio. Vous pouvez cibler différentes plateformes, avec l’émulateur correspondant ou directement sur un téléphone/périphérique connecté par USB à votre PC :

Pour iOS, il vous faudra toutefois un Mac serveur, pour porter le rôle de build. Pour Windows Phone, l’émulateur est directement installé avec le SDK et votre installation Visual Studio et pour Androïd également, le tout a été installé avec les tools Cordova pour VS.

Quelque chose de fort intéressant lorsque vous exécutez votre code est l’utilisation de Ripple (au lieu d’un device ou d’un emulator) :

Ripple est un émulateur Androïd fait par Apache dont la particularité est qu’il est exécuté directement dans Chrome. En fait on pourrait le résumer à une exécution spécifique en mode web dans Chrome, avec l’émulation des caractéristiques d’un téléphone ou d’une tablette. Très pratique car extrêmement rapide pour débuguer ses Apps (plus rapide qu’un émulateur à démarrer, monter en mémoire, etc.). Une documentation sur MSDN est disponible ici : https://msdn.microsoft.com/en-us/library/dn757052.aspx

Si vous essayez d’exécuter l’App avec Ripple, vous pourrez tester votre App dans Chrome, avec un rendu de ce type :

3.2 Ajout de la librairie WinJS

Maintenant que vous avez pris en main l’interface du projet, nous allons ajouter WinJS à notre solution. Pour cela, ouvrez la fenêtre dite « Package Manager Console » et dans la ligne de commande, saisir la commande d’installation de WinJS Install-Package winjs :

Une fois le package installé, un sous-répertoire contenant les scripts, styles etc. de WinJS est visible dans l’arborescence de la solution :

Pour exploiter WinJS dans notre App, on peut inclure dans le fichier index.html les appels au thème CSS à utiliser, ainsi qu’aux 2 fichiers JS du framework :  

<link href="WinJS/css/ui-dark.css" rel="stylesheet" />
<script src="WinJS/js/base.js"></script>
<script src="WinJS/js/ui.js"></script>

3.3 Initialisation de WinJS

Dans le fichier index.js, nous allons initialiser l’application WinJS, avec le code générique suivant :

//var activation = Windows.ApplicationModel.Activation;
var app = WinJS.Application;
var nav = WinJS.Navigation;
var sched = WinJS.Utilities.Scheduler;
var ui = WinJS.UI;

app.addEventListener("activated", function (args) {
    if (args.detail.kind === "Windows.Launch") {
        if (args.detail.previousExecutionState !== 3) {
            //3: terminated
            // TODO: This application has been newly launched. Initialize
            // your application here.
        } else {
            // TODO: This application has been reactivated from suspension.
            // Restore application state here.
        }

        nav.history = app.sessionState.history || {};
        nav.history.current.initialPlaceholder = true;

        // Optimize the load of the application and while the splash screen is shown, execute high priority scheduled work.
        ui.disableAnimations();
        var p = ui.processAll().then(function () {
            return nav.navigate(nav.location || Application.navigator.home, nav.state);
        }).then(function () {
            return sched.requestDrain(sched.Priority.aboveNormal + 1);
        }).then(function () {
            ui.enableAnimations();
        });

        args.setPromise(p);
    }
});

app.oncheckpoint = function (args) {
    // TODO: This application is about to be suspended. Save any state
    // that needs to persist across suspensions here. If you need to 
    // complete an asynchronous operation before your application is 
    // suspended, call args.setPromise().
    app.sessionState.history = nav.history;
};

app.start();

3.4 Utilisation du pattern navigator de WinJS

WinJS offre un pattern très appréciable appelé le « navigator ». Ce pattern permet de gérer une navigation fluide (sans rafraîchissement) entre les pages, ainsi qu’un découpage applicatif très élégant. Le code source du pattern navigator peut être encapsulé au sein d’un script générique, que nous allons également inclure dans notre page :

<script src="scripts/navigator.js"></script>

Une fois ce fichier JS appelé, nous allons pouvoir gérer nos pages de façon élégante et évolutive. Dans notre page index.html, nous allons pouvoir inclure le contrôle de navigation de la façon suivante :  

<div id="contenthost" data-win-control="Application.PageControlNavigator" data-win-options="{home: 'pages/login/login.html'}"></div>

Ceci va indiquer à notre App que le contenu de la page va être retrouvé dans une page login.html dans le sous répertoire pages/login. La page de login va contenir son code de présentation html, et également appeler son propre fichier JavaScript et son propre fichier de style. Ceci va rendre notre application plus maintenable, chaque page de notre App ayant son propre contexte métier et graphique, bien isolé du reste du code :

La page login.html va contenir son propre code html, et appeler ses propres ressources :

<!DOCTYPE html>
<html>
<head>
    <meta charset="utf-8" />
    <title>Login</title>

    <link href="login.css" rel="stylesheet" />
    <script src="login.js"></script>
</head>
<body>
    <div class="page fragment">
        <header class="page-header" aria-label="Header content" role="banner">
            <h1 class="titlearea win-type-ellipsis">
                <span class="pagetitle">Login</span>
            </h1>
        </header>
        <section class="page-section" aria-label="Main content" role="main">

                <!-- contenu de la page -->

        </section>
    </div>
</body>
</html>

Le fichier login.js pourra contenir le code métier propre à sa page html, avec des fonctions appelées automatiquement lors de certains évènements, comme « ready », « unload », etc. : 

// For an introduction to the Page Control template, see the following documentation:
// http://go.microsoft.com/fwlink/?LinkId=232511
(function () {
    "use strict";

    WinJS.UI.Pages.define("/pages/login/login.html", {
        // This function is called whenever a user navigates to this page. It
        // populates the page elements with the app's data.
        ready: function (element, options) {
            // TODO: Initialize the page here.
        },

        unload: function () {
            // TODO: Respond to navigations away from this page.
        },

        updateLayout: function (element) {
            /// <param name="element" domElement="true" />

            // TODO: Respond to changes in layout.
        }
    });
})();

Avec cette structuration de pages, nous allons pouvoir maintenant réaliser le contenu de notre application, faire des requêtes à des sites SharePoint, affiché le contenu dans des contrôles HTML 5 efficaces et beaux, et tout ça dans une App qui va pouvoir s’exécuter aussi bien sur Windows, Windows Phone, Androïd, iPhone et iPad ! 

4. Authentification à Office 365 et SharePoint Online

Avant d’envisager de faire des requêtes aux API de SharePoint Online ou Office 365, il est indispensable de gérer correctement l’authentification. Comme vous le savez sans doute, la brique de gestion et de connexion des utilisateurs d’Office 365 est basée sur Azure Active Directory (dit AAD).

Azure Active Directory, comme tous les services d’Office 365 expose un bon nombre de web services et API pour permettre de gérer par programmation l’authentification à ses services. AAD évolue vite et propose régulièrement des nouveaux services et méthodes d’authentification (par exemple récemment a été ajouté le support de l’authentification Multi-Facteurs, dite MFA).

C’est là notamment qu’intervient les Office 365 API. Pas besoin d’être un expert de l’authentification et des services AAD pour être capable de développer un système d’authentification. Pas besoin de stocker le login/mot de passe de l’utilisateur, ni de se préoccuper des évolutions futures de la plateforme : Office 365 API vous offre des moyens simples pour prendre en charge ses méthodes d’authentification !

Voici comment procéder : Faites un clic droit sur le nom de votre projet dans la fenête « Solution Explorer », puis aller dans le menu « Add », puis cliquer sur « Connected Service… » :

Cliquer dans le menu gauche sur « Office 365 APIs » dans la partie Office 365 : 

Saisir votre compte Office 365 :

Une fois connecté, la liste de vos services accessible sur votre tenant Office 365 va apparaître. Cliquer sur « Sites », puis sur « Permissions » à droite :

Sélectionner la permission « Read items in all site collections », puis cliquer sur « Apply » :

Une fois la fenêtre précédente validée, des nouveaux fichiers de sources sont ajoutées dans votre solution, dans un sous-répertoire « services/office365 » :

Si vous ouvrez le fichier « settings.js », vous allez voir le paramétrage spécifique à votre application, avec les informations d’identification (client ID) et les adresses permettant à votre application de dialoguer avec le fournisseur d’authentification de votre tenant :

var O365Auth;
(function (O365Auth) {
    (function (Settings) {
        Settings.clientId = 'you-client-id-guid';
        Settings.authUri = 'https://login.windows.net/common/';
        Settings.redirectUri = 'http://localhost:4400/services/office365/redirectTarget.html';
    })(O365Auth.Settings || (O365Auth.Settings = {}));
    var Settings = O365Auth.Settings;
})(O365Auth || (O365Auth = {}));

 Pour appeler et inclure les services d’Office 365 dans notre projet, les choses sont plutôt simples, il nous suffit d’inclure l’appel au fichier « o365loader.js » qui va se charger d’inclure les autres JS nécessaires :

<!-- Office365 Service Libraries -->
<script src="services/office365/scripts/o365loader.js"></script>

Lorsque l’utilisateur va cliquer sur le bouton de Login, l’API Office 365 nous permet d’initialiser le contexte d’authentification, puis de demander le jeton pour accéder aux ressources SharePoint :

authContext = new O365Auth.Context();
discoveryContext = new O365Discovery.Context();
discoveryContext.services(authContext.getAccessTokenFn('Microsoft.SharePoint')).then((function (value) {
    capabilities = value;
    getCurrentUser();
}).bind(this), function (error) {
    var errorAsString = JSON.stringify(error);
});

On peut alors extraire les informations du profil utilisateur et naviguer vers la page home.html :  

// Get currently logged in user
function getCurrentUser() {
    authContext.getIdToken("https://outlook.office365.com/").then((function (token) {
        authToken = token;

        var options = { token: authToken, context: authContext, capabilities: capabilities };
//Bind the user name
var userName = { name: authToken.givenName + ' ' + authToken.familyName };
var personDiv = document.querySelector('#userName');
WinJS.Binding.processAll(personDiv, userName);

        WinJS.Navigation.navigate("/pages/home/home.html", options);

    }).bind(this), function (reason) {
        console.og(reason.message);
    });
}

Dans notre App, l’utilisateur peut maintenant s’authentifier dans l’App en trois étapes : 1 : Il clique sur le bouton Login, 2 : Il est invité à saisir ses crédentials sur son système d’authentification de son tenant Office 365, 3 : il est redirigé vers l’App :

5. Utilisation des web services de SharePoint Online

Maintenant que l’utilisateur est capable de se connecter, on peut réaliser des requêtes sur des ressources contenu au sein de site SharePoint.

Pour cet exemple, nous allons utiliser deux listes au sein d’un site d’équipe pour respectivement afficher des annonces et les derniers documents d’une bibliothèque SharePoint.

Exemple de listes Annonce :

Exemple de bibliothèque SharePoint Online :

Pour lire les données d’une liste ou d’une bibliothèque SharePoint, on peut utiliser les web services de l’API REST. On peut par exemple lister les données de la bibliothèque « Annonces » via un appel du type :

https://YOURTENANT.sharepoint.com/sites/WinJSSampleSite/_api/lists/getbytitle('Annonces')/items?$select=Title,Body,Modified

Le code suivant montre comment exécuter la requête HTML avec WinJS.xhr et lister les résultats :

//Request the latest announcements
var rootSiteRessourceId;
options.capabilities.forEach(function (v, i, a) {
    if (v.capability === 'RootSite') {
        rootSiteRessourceId = v.resourceId;
    }
});

options.context.getAccessToken(rootSiteRessourceId).then((function (bearerToken) {
    var options = {
        url: "https://YOURTENANT.sharepoint.com/sites/WinJSSampleSite/_api/lists/getbytitle('Annonces')/items?$select=Title,Body,Modified",
        type: 'GET',
        headers:
            {
                "accept": "application/json;odata=verbose",
                "content-type": "application/json;odata=verbose",
                "Authorization": "Bearer " + bearerToken
            }
    };
    WinJS.xhr(options).done(
        function (result) {

            var feed = JSON.parse(result.responseText);
            for (var i = 0, len = feed.d.results.length; i < len; i++) {
                var item = feed.d.results[i];

                latestNews.push(
                    {
                        name: item["Title"],
                        icon: "images/calendar.png",
                        time: formatDate(item["Modified"]),
                        readStateColor: "rgba(255, 255, 255, 4)",
                        readStateFont: "Segoe UI Semibold",
                        messageText: removeHtml(item["Body"])
                    });

            }

6. Afficher des données et interface graphique avec WinJS

Une fois la requête exécutée nous pouvons afficher les résultats à l’aide d’un contrôle ListView de WinJS. Ce contrôle permet de « binder » une liste de résultats à partir d’une template HTML. On peut également utiliser le contrôle WinJS.UI.Pivot pour afficher les deux listes sous la forme d’onglets :

<div class="messageTemplate" data-win-control="WinJS.Binding.Template">
    <div class="message">
        <div class="userIcon"><img src="#" data-win-bind="src: icon" width="48"/></div>
        <div class="messageContent">
            <div class="contactInformation">
                <div class="contactName" data-win-bind="textContent: name"></div>
                <div class="contactTime" data-win-bind="textContent: time; style.color: readStateColor; style.fontFamily: readStateFont"></div>
            </div>
            <div class="messagePreview" data-win-bind="textContent: messageText; style.color: readStateColor; style.fontFamily: readStateFont"></div>
        </div>
    </div>
</div>

<div id="messageList" data-win-control="WinJS.UI.Pivot" data-win-options="{ selectedIndex: 0 }">
                
    <div class="pivotItem" data-win-control="WinJS.UI.PivotItem" data-win-options="{ 'header': 'Latest News' }">
        <div data-win-control="WinJS.UI.Repeater" data-win-options="{ data: DataSet.LatestNews, template: select('.messageTemplate') }"></div>
    </div>

    <div class="pivotItem" data-win-control="WinJS.UI.PivotItem" data-win-options="{ 'header': 'Latest Docs' }">
        <div data-win-control="WinJS.UI.Repeater" data-win-options="{ data: DataSet.LatestDocs, template: select('.messageTemplate') }"></div>
    </div>

</div>

Dans le code JavaScript associé, on peut initialiser les listes : 

var latestNews = new WinJS.Binding.List([]);
var latestDocs = new WinJS.Binding.List([]);

WinJS.Namespace.define("DataSet", {
    LatestNews: latestNews,
    LatestDocs: latestDocs
});

Voici le rendu des écrans sur un téléphone en mode vertical :

Ou en mode horizontal :

Conclusion

Il est simple de développer une App mobile capable de pleinement exploiter les API d’Office 365 pour interroger un site SharePoint Online. Grâce aux extensions Apache Cordova pour Visual Studio, on peut facilement rendre cette application compatible pour les types de devices mobiles comme Windows Phone, Androïd ou iOS.

Proposer des applications mobiles connectées avec ses sites Intranet SharePoint, sa messagerie Exchange Online, son espace OneDrive ou encore son Office Graph sont autant de choses facilement réalisables grâce à l'Office 365 API.

MyWinJSCordovaApp.zip

Introduction

Si vous aimé Yammer et SharePoint 2013, vous vous êtes probablement souvent posé la question de comment faire des scénarios d’intégration entre ces deux outils. Même si cela est parfois mal connu, il existe un grand nombre de méthodes pour être capable d’intégrer ces deux solutions.

Parmi elles, on peut citer deux méthodes particulièrement utiles pour un grand nombre de projets :

1. Yammer Embed : il s’agit d’une librairie JavaScript pour très simplement afficher un flux Yammer dans un site SharePoint.  Cette méthode n’est pas détaillée dans cet article. Si vous souhaitez plus d’information, je vous invite à lire mon billet de blog précédent, qui explique les fondamentaux à connaître sur Yammer Embed.
2. Yammer API : il s’agit de l’interface de programmation de Yammer. C’est celle que nous allons détailler et présenter dans ce billet.

Yammer API (pour Application Program Interface) est un kit de programmation disponible dans différents langages, qui va vous permettre d’interagir avec Yammer pour réaliser un bon nombre d’actions. 

Dans cet article, nous verrons différents exemples de code nous permettant d’afficher des données de Yammer dans un site SharePoint, ou au contraire, de pousser des éléments vers Yammer depuis SharePoint.

Pour cet article, je souhaite remercier chaleureusement Loic Da Costa, avec qui j’ai eu la chance de pouvoir collaborer sur le sujet.

Yammer API : pour quoi faire ?

Hormis les scénarios d’inclusion d’un fil de discussion Yammer dans une page SharePoint qui peut être réalisé avec Yammer Embed, tous les autres scénarii d’interconnexion applicative peuvent être réalisés avec l’API Yammer.

Si vous savez utiliser l’API Yammer, vous allez pouvoir réaliser un bon nombre d’idée d’intégration, comme par exemple :

• Réaliser une application qui se base sur l’authentification Yammer ;
• Réaliser une application qui est capable d’extraire et d’utiliser les informations du profil de l’utilisateur, comme par exemple sa photo, ses groupes d’appartenance, etc.
• Réaliser une application qui est capable de créer automatiquement du contenu dans Yammer, comme par exemple pour pousser un lien vers une donnée stockée dans SharePoint ;
• Etc.

Principes des interfaces de programmation de Yammer

Il existe plusieurs types d’interface de programmation pour faire de l’intégration avec Yammer. Parmi elles, on peut citer : le SDK JavaScript, Ruby, Python, iOS, .Net ou encore Windows Phone 8.

L’objectif de ces SDK est relativement identique : encapsuler du code qui appelle les web services  de Yammer (dits « EndPoints » – ou « points de terminaison » - utilisant la technologie REST) pour vous faciliter les manipulations par code.

Dans cet article, nous n’allons utiliser que le SDK JavaScript, car il se prête très bien à une intégration simple et rapide avec SharePoint 2013.

Si vous souhaitez lire la documentation de l’équipe Yammer sur le sujet, je vous suggère la doc officielle, référencée dans le « Developper Center » de Yammer. Je vous invite à lire les pages suivantes, qui sont riches en information :

• Point d’entrée de la documentation : https://developer.yammer.com/ 
• Comprendre les mécanismes d’authentification : https://developer.yammer.com/v1.0/docs/authentication
• Présentation des concepts de l’Open Graph : https://developer.yammer.com/v1.0/docs/open-graph
• Documentation du SDK JavaScript : https://developer.yammer.com/v1.0/docs/js-sdk
• Documentation des web services REST : https://developer.yammer.com/v1.0/docs/rest-api-rate-limits

Il est également pratique de savoir que toute la communauté des développeurs Yammer échange sur la plateforme Stack Overflow. Vous pouvez trouver un grand nombre d’exemples de code et des réponses à vos questions ici : http://stackoverflow.com/tags/yammer/

Toute utilisation de l’API Yammer nécessite forcément deux concepts de base : réaliser une App pour Yammer et gérer l’authentification.

Nous allons présenter ces concepts dans les chapitres suivants.

Déclarer une application Yammer

Un point important à comprendre avant de se lancer dans un développement avec Yammer, est le concept d’Application.

Pour pouvoir communiquer de façon sécurisée entre un site SharePoint et un réseau Yammer, on doit au préalable établir un « lien  sécurisé » entre nos développements et Yammer. Cela passe par le concept d’App. Une App Yammer est essentiellement une déclaration au sein d’un réseau, permettant d’obtenir des paramètres que nous pourrons utiliser dans un code source pour communiquer avec Yammer de façon sécurisée.

La procédure officielle pour déclarer une nouvelle App dans Yammer est disponible à l’adresse suivante : https://developer.yammer.com/v1.0/docs/app-registration

Pour déclarer une nouvelle App Yammer, vous pouvez suivre la procédure suivante :

Dans le bloc de gauche de l’écran, cliquer sur « Enregistrer une nouvelle App » :

Remplissez le formulaire et tous ses champs. Pour la zone de saisie « site web », bien remplir avec l’adresse du site SharePoint qui va contenir les développements qui vont communiquer avec Yammer, puis cliquez sur « Continuer » :

Une fois créée, votre application est visible et peut être publiée grâce à un formulaire en 3 étapes : les informations de base, le paramétrage sur la façon d’apparaître dans l’annuaire des Apps et enfin du paramétrage spécifique si vous souhaitez personnaliser le « vocabulaire » open graph de votre application. Le 1^ier écran est très important, c’est ici que vous allez trouver l’identifiant (clé) de votre App, ainsi que la clé secrète. Garder précieusement l’identifiant Client, nous serons amené à nous en resservir par la suite :

Dans le menu de gauche, cliquer sur « Info de base » pour accéder aux informations génériques de l’App.

L’écran se décompose en deux parties :

• Informations sur l’Application & Informations de support : ces deux sections contiennent les informations sur l’App que vous venez de saisir.
• Informations d’installation : cette section est très importante. Vous devez saisir l’adresse de redirection (que vous avez normalement déjà saisie sur le formulaire précédent) et SURTOUT les adresses des domaines d’origines qui vont appeler l’API Yammer. Il est primordial de bien préciser ces informations, pour que l’authentification fonctionne bien. Vous devez saisir ici les domaines des sites SharePoint. Pas besoin de saisir les adresses complètes de vos sites SharePoint, mais uniquement les domaines. Ne saisissez pas les adresses avec des « wildcards » (type : https://*.sharepoint.com), mais plutôt des adresses complètes. Prenons un exemple : vous possédez un tenant Office 365 appelé « mycontoso ». Vos sites SharePoint sont disponibles depuis le domaine https://mycontoso.sharepoint.com avec des adresses du type https://mycontoso.sharepoint.com/sites/sample. La valeur à remplir ici est donc bien https://mycontoso.sharepoint.com.   

Astuce : Saisir ici des adresses sans le slash final « / ». 

Cliquer ensuite sur « Annuaire des applications ». Vous pouvez alors configurer la façon dont l’App apparaîtra. Vous pouvez également fournir des images à différents formats, qui seront ré-exploitées par Yammer pour vous faire apparaître aux différents endroits du site et de l’annuaire.

 Au-delà des informations de description de l’App, il est important de noter deux choses sur cet écran :

1. Vous remarquerez la présence d’une case à cocher « Jeton ». Cette case peut vous aider à dialoguer et échanger les paramètres d’authentification grâce à des jetons. Ne la cochez pas, dans notre exemple nous n’en n’aurons pas besoin ;
2. La présence d’un bouton « Déployer » en bas du formulaire. Ce bouton est impératif dans pour que l’App soit visibles et utilisables par vos utilisateurs.

Remplissez les champs, puis cliquez sur le bouton « Déployer » :

Après avoir enregistré et déployé votre App sur votre réseau, les boutons de cet écran changent et apparaissent de la façon suivante :

Attention : ne cliquer pas sur le bouton « Soumettre pour vérification ». Ce bouton que permet de soumettre votre application pour apparaître dans l’annuaire global des App Yammer et donc être disponibles pour tous les networks managers. A ce stade, ce n’est probablement pas ce que vous souhaitez faire.

Dans cet exemple, nous n’allons pas configurer le 3ieme écran, relatif au « tunning » de l’Open Graph pour une raison simple : nous n’en aurons pas besoin. En ayant déployé notre App sur le réseau, celle-ci est maintenant visible et opérationnelle.

Nous pouvons maintenant commencer l’intégration de cette App au sein d’un site SharePoint 2013 !

Référencer la librairie JavaScript Yammer

Pour référencer la librairie JavaScript Yammer, nous devons inclure dans nos pages un appel au fichier JS de Yammer. Inclure un appel à une librairie peut être fait de plusieurs façons dans SharePoint 2013, via directement une édition de la page et l’ajout d’une WebPart de type « Editeur de script », ou directement via une modification du code de votre master page.

C’est à travers cette référence, que nous allons fournir à Yammer notre CLIENT ID.

L’inclusion doit être réalisée avec la forme suivante :

<script type="text/javascript" data-app-id="YOUR-APP-CLIENT-ID" src="https://c64.assets-yammer.com/assets/platform_js_sdk.js"></script>

 Dans l’exemple de l’App que nous venons de créer, le code serait donc le suivant :

<script type="text/javascript" data-app-id="E1mOzs6tUYIEq93MrNUA" src="https://c64.assets-yammer.com/assets/platform_js_sdk.js"></script>

Astuce : Ne copiez/collez pas directement le code précédent, pensez à bien remplacer l’argument « data-app-id » par votre propre identifiant, sans quoi, vos appels à l’API ne fonctionneront pas !

Maintenant que nous avons correctement référencé la librairie JavaScript, nous sommes prêts pour faire des appels à l’API Yammer.

Gérer la connexion de l’utilisateur par Yammer

Concepts de l’authentification Yammer

Pierre angulaire de toute intégration d’une solution dans une autre : l’authentification ! Si l’on souhaite communiquer ou récupérer des informations de Yammer depuis un site SharePoint, il est impératif que l’on soit capable de connaître l’identité Yammer de l’utilisateur.

Pour cela, nous allons voir deux concepts importants :

1. Comment détecter si l’utilisateur est connecté sur Yammer
2. Comment déclencher une authentification si l’utilisateur n’est pas encore connecté

Méthode de connexion « tout en un »

L’API JavaScript de Yammer nous offre un mécanisme préconstruit pour réaliser ces deux opérations, grâce à la méthode « yam.connect.loginButton » :

yam.connect.loginButton

Cette méthode va automatiquement essayer de détecter le statut d’authentification de l’utilisateur et éventuellement afficher le bouton de connexion si l’utilisateur n’est pas connecté.

Le code JavaScript pour réaliser cette opération est le suivant :

<span id="yammer-login"></span>
<script>
  yam.connect.loginButton('#yammer-login', function (resp) {
    if (resp.authResponse) {
      document.getElementById('yammer-login').innerHTML = 'Bravo vous êtes connecté !';
    }
  });
</script>

Dans le cas où l’utilisateur n’est pas encore connecté, le bouton suivant va apparaître :

Si l’utilisateur clique sur le bouton, une pop-up de ce type va apparaître à l’utilisateur :

Une fois identifié, l’utilisateur sera maintenant correctement reconnu et nous allons pouvoir faire des appels à l’API Yammer.

Une chose importante à se souvenir est que la réponse de l’authentification est fournie grâce à l’argument « resp » (dans l’exemple ci-dessus), qui possède un certains nombres de membres qui peuvent nous intéresser.

Voici un rapide détail de ces membres :

Méthode de connexion « pas à pas »

Un défaut de la méthode présentée précédemment, même si elle est très pratique, est que le bouton de connexion proposé par Yammer possède un texte en anglais. De plus, pour des raisons spécifiques à un projet, on pourrait vouloir personnaliser ce bouton.

Dans ce cas, pas de panique, l’API JavaScript de Yammer propose une méthode alternative :

yam.platform.getLoginStatus(callback, [forceRefresh])

Cette méthode va simplement vérifier que l’utilisateur est bien connecté et vous renvoyer la réponse. Dans le cas où ce n’est pas le cas, vous pourriez déclencher l’authentification via une méthode également préconstruite :

yam.platform.login([opts], [callback])

 Prenons un exemple qui va implémenter ces deux méthodes :

<div id="yammerapppopin" style="display: block;">
    Pour une utilisation optimale du site, nous vous recommandons de vous connecter à Yammer.
    Vous pouvez le faire simplement en cliquant sur le bouton suivant :

    <div style="clear:left">
    </div>
    <a onclick="javascript:LaunchLogin();" href="#">
        <img src="/images/yammer-signin.gif">
    </a>
</div>

<script type="text/javascript">

function LaunchLogin() {
    yam.platform.login(function (response) {
        if (response.authResponse && response.status == "connected") {
            location.reload();
        }
    });
}

yam.platform.getLoginStatus(
	function (response) { 		
		if (response.authResponse) {
            //L'utilisateur est bien connecté
		    console.log("logged in");
		}
		else {
		    //L'utilisateur n'est pas connecté, on affiche le 
		    //message de connexion
		    document.getElementById("yammerapppopin").style.display = "block";
		}
	}
);

</script>

Astuce : Si vous n’avez pas bien renseigné le champ « Origine JavaScript » depuis le formulaire d’enregistrement de l’App, vous pouvez avoir des problèmes de connexions non autorisées.

Exemple 1 : récupérer les informations du profil Yammer

Voici un 1^ier cas d’usage de l’API Yammer qui peut nous être très pratique : récupérer les informations du profil Yammer depuis un site SharePoint. En effet, on peut vouloir par exemple réaliser une interface qui soit capable d’afficher des informations provenant de Yammer, comme par exemple pour faire un lien direct vers son profil Yammer, ou encore pour récupérer la photo de l’utilisateur qu’il aurait renseigné sur le réseau social. Un bon moyen donc, par exemple, de gérer une expérience unifiée pour une solution qui se base à la fois sur SharePoint et sur Yammer.

Toutes les requêtes vers les API Yammer doivent suivre quelques règles simples :

• Une méthode yam.platform.request permet de réaliser une requête vers un web service de Yammer. Cette méthode a l’avantage d’être simple et de prendre en charge le passage des paramètres liés à l’authentification par exemple
• Différents web services sont disponibles pour travailler sur les objets utilisateurs, et sont à fournir via l’argument url de la méthode request.

Pour récupérer des informations sur l’utilisateur connecté, un point de terminaison spécifique est disponible à l’adresse https://api.yammer.com/api/v1/users/current.json.

Voici un exemple de son utilisation, qui permettent de récupérer la photo de l’utilisateur, son nom complet, ainsi qu’un lien vers sa page de profil :

<script type="text/javascript">

yam.platform.request({
    url: "https://api.yammer.com/api/v1/users/current.json",
    method: "GET",
    success: function (user) {

        //Log dans la console le profil utilisateur
        console.dir(user);
        //Récupère l'image de l'utilisateur
        var userImg = user.mugshot_url;
        //Récupère l'image de l'utilisateur
        var userFullName = user.full_name;
        //Récupère l'adresse du profil utilisateur
        var userWebUrl = user.web_url;
    },
    error: function (mssg) {
        console.log("There was an error with the request.");
    }
});

</script>

Si vous souhaitez récupérer des informations d’un utilisateur spécifique (et non de l’utilisateur en cours), vous pourriez également utiliser d’autres web services dédiés.

Par exemple, pour récupérer les informations d’un utilisateur depuis son adresse email, un point de terminaison est disponible à l’adresse suivante :

https://api.yammer.com/api/v1/users/by_email.json?email=<adresse-email>

Voici un exemple de méthode pour récupérer les informations d’un profil utilisateur depuis son adresse email :

<script type="text/javascript">

yam.platform.request(
    {
        url: "https://api.yammer.com/api/v1/users/by_email.json?email=toto@contoso.com",
        method: "GET",
        success: function (user) {
            //Log dans la console le profil utilisateur
            console.dir(user);
        },
        error: function (msg) {
            console.log("There was an error with the request.");
        }
    }
);

</script>

Chaque utilisateur possède un identifiant unique sous Yammer, du coup, si vous possédez cet identifiant, vous pouvez également faire une requête pour obtenir les informations complémentaires du profil :

<script type="text/javascript">

yam.platform.request(
	{
		url: "https://api.yammer.com/api/v1/users/" + userId + ".json",
		method: "GET",
		success: function (user) {
		    //Log dans la console le profil utilisateur
		    console.dir(user);
		},
		error: function (msg) {
		    console.log("There was an error with the request.");
		}
	}
);

</script>

Exemple 2 : récupérer les groupes Yammer auxquels l’utilisateur appartient

Il est assez fréquent de vouloir afficher les groupes Yammer d’un utilisateur sur un site SharePoint. Notamment lorsque l’on propose un Intranet réalisé avec SharePoint, dans lequel on souhaite avoir sur la page d’accueil une vue relativement « profilée » pour l’utilisateur en référençant les différents espaces auxquels il peut avoir accès.

Pour ce faire, les choses sont plutôt simples, on peut appeler le web services groups.json qui peut prendre un argument mine=1 qui va retourner les groupes d’appartenance de l’utilisateur actuel :

<script type="text/javascript">

yam.platform.request({
    url: "https://api.yammer.com/api/v1/groups.json?mine=1",
    method: "GET",
    success: function (groups) {

        for (var i = 0; i < groups.length; i++) {

            var curGroup = groups[i];
            //Log dans la console les informations du groupe
            console.dir(curGroup);
            //Nom du groupe
            var groupName = curGroup.full_name;
            //URL de l'image descriptive
            var groupImage = curGroup.mugshot_url;
            //URL du groupe
            var groupUrl = curGroup.web_url;
            //Niveau de sécurité du groupe (private, public)
            var groupPrivacy = curGroup.privacy;
            //Description du groupe
            var groupDesc = curGroup.description;
            //Nombre d'utilisateurs au sein du groupe
            var groupMembers = curGroup.stats.members;
        }

    },
    error: function (mssg) {
        console.log("There was an error with the request.");
    }
});

</script>

Exemple 3 : publier un message dans Yammer par programmation

Maintenant que nous avons vu comment récupérer par programmation des informations stockées dans Yammer, voyons maintenant comment publier des informations vers Yammer depuis SharePoint.

Pour poster un message, il existe un web service disponible à l’adresse https://api.yammer.com/api/v1/messages.json qui permet, via un appel de type POST, d’envoyer des données contenant le message. Les données doivent être formatées avec une forme spécifique et des paramètres donnés. Les deux paramètres obligatoires sont à minima l’identifiant du groupe Yammer, ainsi que le corps du message.

Voici un exemple d’un post simple d’un message par programmation :

<script type="text/javascript">

function PostYammer(group_id, message, success, fail) {

    var yammerData;
    yammerData = { group_id: group_id, body: message };
    
    yam.platform.request(
        {
            url: "https://api.yammer.com/api/v1/messages.json",
            method: "POST",
            data: yammerData,
            success: function (msg) { success(msg); },
            error: function (msg) { fail(msg); }
        }
    );
}

</script>

Lorsque vous réalisé la création d’un message par programmation, il est important de noter que le nom de votre Application va apparaître à côté du message.

Par exemple, voici une capture d’un message automatiquement publiée depuis une App appelée « Contoso Intranet » :

On pourrait également fournir à Yammer, des « topics » (ou tag) à attacher à un message. Même si chaque tag possède un identifiant unique, pas besoin de créer un nouveau tag puis de fournir son identifiant : il suffit de fournir le tag de façon textuelle. Lorsque l’on construit « l’enveloppe » des données à envoyer à Yammer, on peut associer des arguments de type « topic1 » numérotés (exemple : topic1, topic2, topic3, etc.)

Voici un exemple de code pour publier un message avec un topic associé :

<script type="text/javascript">

function PostYammerWithTopic(group_id, message, topic, success, fail) {

    var yammerData;
    yammerData = { group_id: group_id, body: message, topic1: topic };

    yam.platform.request(
        {
            url: "https://api.yammer.com/api/v1/messages.json",
            method: "POST",
            data: yammerData,
            success: function (msg) { success(msg); },
            error: function (msg) { fail(msg); }
        }
    );
}

</script>

Le résultat dans Yammer sera le suivant :

On pourrait également ajouter à un message des personnes à notifier. Pour notifier des utilisateurs, il faut ajouter un paramètre complémentaire en renseignant un tableau des utilisateurs ciblés.

Voici un exemple d’un message publié avec une notification d’un utilisateur spécifique :

<script type="text/javascript">

function PostYammerWithNotification(group_id, message, userCC, success, fail) {

    var yammerData;
    yammerData = { group_id: group_id, body: message };
    yammerData.cc = "[[user:" + userCC + "]]";

    yam.platform.request(
        {
            url: "https://api.yammer.com/api/v1/messages.json",
            method: "POST",
            data: yammerData,
            success: function (msg) { success(msg); },
            error: function (msg) { fail(msg); }
        }
    );
}

</script>

Le résultat dans Yammer sera le suivant :

Ca y’est, les fondamentaux de l’envoi de message à Yammer depuis SharePoint par programmation n’a plus de secret pour vous ? Vous êtes prêt à aller plus loin en joignant un objet Open Graph à vos messages !

Exemple 4 : publier un message dans Yammer avec un objet Open Graph rattaché

Une autre capacité intéressante de l’API Yammer est de pouvoir ajouter à un message un objet Open Graph. Un objet Open Graph est un objet qui sera identifiable visuellement au sein du fil de discussion.

Un objet Open Graph possèdera un identifiant unique sous Yammer, qui permettra ensuite de le retrouver ou de voir tous les messages publiés relativement à cet objet dans les différents groupes de votre réseau. 

Prenons un exemple simple pour lequel l’attachement d’un objet Open Graph peut avoir du sens. Imaginons que sur notre Intranet réalisé avec SharePoint, nous ayons un calendrier des évènements internes qui est entretenu par notre service de communication. Lorsque les contributeurs publient un nouvel évènement dans cet agenda, nous souhaiterions qu’un message soit automatiquement créé au nom du contributeur dans un groupe Yammer correspondant aux communications internes. Ce message devra avoir un code visuel spécifique (pour tout de suite identifier qu’il s’agit d’un évènement d’un calendrier), et lorsque l’utilisateur va cliquer sur l’évènement dans le fil de discussion, il sera redirigé vers l’agenda hébergé sur SharePoint. Un excellent moyen donc de donner de la visibilité à vos contenus stockés sur votre Intranet et bénéficier à moindre effort de la visibilité de Yammer pour promouvoir vos données !

Lorsque l’on souhaite créer un objet Open Graph et l’associer à un message, on peut fournir les paramètres suivants :

• og_url : adresse web (url) vers laquelle l’utilisateur va être redirigé s’il clique sur l’objet Open Graph
• og_title : titre de l’objet Open Graph
• og_image : adresse (url) d’une image qui sera affichée à côté de l’objet
• og_description : description associée à l’objet Open Graph

Voici un exemple de fonction JavaScript qui permet de publier un message en attachant un objet Open Graph :

<script type="text/javascript">

function PostYammerWithOpenGraph(group_id, message, openGraphUrl, openGraphTitle, openGraphImage, openGraphDescription, success, fail) {

    var yammerData;

    yammerData = {
        group_id: group_id, body: message,
        og_url: openGraphUrl, og_title: openGraphTitle, og_image: openGraphImage, og_description: openGraphDescription
    };
    
    yam.platform.request(
		{
		    url: "https://api.yammer.com/api/v1/messages.json",
		    method: "POST",
		    data: yammerData,
		    success: function (msg) { success(msg); },
		    error: function (msg) { fail(msg); }
		}
	);
}

</script>

Avec l’exemple détaillé ci-dessus, voici un rendu d’un message avec un objet Open Graph attaché et la façon dont les paramètres sont exploités dans le fil de discussion :

Astuce : Le paramètre og_image doit contenir une image dont l’adresse est accessible sans authentification de la part de l’utilisateur. N’héberger donc pas cette image sur votre site SharePoint sécurisé, mais utilisez plutôt une image disponible dans un entrepôt d’images disponibles publiquement sur Internet. 

Limites à connaître avec l’API Yammer

Même si en théorie on peut aller très loin dans les scénarios d’automatisation de traitement entre SharePoint et Yammer grâce à l’API Yammer, il faut bien garder à l’esprit qu’une limitation existe sur l’API Yammer : chaque points de terminaison Yammer possède ses propres limites en terme de nombre de requêtes pouvant être effectuées dans un certain laps de temps.

Ceci est malheureusement obligatoire pour les équipes Yammer, pour ne pas permettre la réalisation d’attaques de type « Dénis de service » (très grand nombre de requêtes qui sature le service). Le système doit pouvoir avoir des « gardes fous », limitant le nombre d’appel à des services dans un intervalle de temps donné. Tout appel qui va dépasser cette limite vous renverra une erreur HTTP de type 429 (Too Many Requests).

La documentation de Yammer est bien fournit sur ce sujet et vous explique les limites pour chaque point de terminaison. Cette documentation est disponible à l’adresse suivante :

https://developer.yammer.com/v1.0/docs/rest-api-rate-limits

Conclusion

L’API de Yammer est massivement orientée web services. C’est même une constante d’architecture avec Yammer : ce que l’on fait par l’interface graphique de yammer.com est réalisable au final par un ou plusieurs appels à des points de terminaisons REST/JSON.

Le SDK JavaScript nous offre un moyen simple et rapide pour envisager des scénarios avancés d’interconnexion entre Yammer et SharePoint 2013 qui répondraient à nos besoins métier.

On peut facilement imaginer afficher des informations provenant de Yammer dans un site SharePoint (exemple : lister les groupes Yammer de l’utilisateur sur la page de profil SharePoint), ou encore utiliser les messages en push pour émettre des informations depuis SharePoint (exemple : publier de façon automatique des messages dans un réseau depuis une application métier).

Cet article n’est pas exhaustif vis-à-vis des scénarios que l’on peut imaginer réaliser ni des points de terminaisons disponibles dans Yammer. Il y’a beaucoup d’autres (comme la recherche, etc.) qui peuvent vous être utiles pour vos idées d’interconnexion entre SharePoint et Yammer !

Garder toutefois à l’esprit deux points importants :

• Bien implémenter l’expérience de connexion des utilisateurs ;
• Faire avec les limites en termes de nombres de requêtes simultanées par utilisateur.

Enjoy SharePoint & Yammer !

Si vous êtes utilisateur de Yammer et que vous souhaitez facilement utiliser des flux Yammer au sein d’un site SharePoint 2013 (Online ou Server), cet article est fait pour vous !

Si vous ne connaissez pas encore Yammer Embed, c’est LA bonne méthode pour utiliser facilement et rapidement Yammer dans n’importe quel site SharePoint, que ce soit un site de publication ou un site d’équipe.

Dans cet article nous allons voir comment inclure un flux Yammer dans une page SharePoint, comment personnaliser ce flux, ainsi que quelques trucs et astuces pour apporter, avec peu d’effort, un maximum de visibilité à vos contenus stockés sur SharePoint.

C’est quoi Yammer Embed ?

Yammer Embed est une librairie JavaScript qui permet en quelques lignes d’inclure dans un site SharePoint (Online ou Server) des données provenant de Yammer.

Par exemple, avec Yammer Embed on peut afficher, sur une page d’un Intranet SharePoint, le flux d’un groupe spécifique de Yammer, ou encore les données correspondant aux flux personnel d’une personne (les éléments suivis par l’utilisateur).

Ceci va nous permettre de pleinement bénéficier des fonctionnalités sociales de Yammer, comme pouvoir répondre directement à des messages depuis un site SharePoint, comment « liker » une page tout en restant dans l’interface de SharePoint. Embed peut également nous permettre d’afficher sur une page une zone de commentaires pour afficher toutes les publications réalisées sur Yammer relatives à un sujet spécifique.

La documentation officielle de Yammer Embed est disponible à l’adresse suivante :

https://developer.yammer.com/v1.0/docs/embed

Si vous êtes déjà utilisateur de Yammer, sans le savoir vous avez peut-être déjà vu du code Yammer Embed. En effet, lorsque vous allez dans un groupe Yammer, vous pouvez voir sur la droite une widget appelée « Options d’Accès » :

En cliquant sur « Intégrer ce groupe sur votre site », Yammer vous affiche du code JavaScript automatiquement généré, pour vous permettre d’afficher le contenu du fil de discussion du groupe Yammer au sein d’un site web :

Les options de Yammer Embed

Lorsque vous utilisez le bouton d’intégration à un site depuis un groupe Yammer, le code JavaScript qui vous est proposé est un code avec des options générées par défaut.

Vous pouvez toutefois aller bien plus loin dans la personnalisation, avec un certain nombre d’options intéressantes.

Voici un tableau vous expliquant quelques-unes des options disponibles :

Il est intéressant de savoir que l’équipe Yammer vous propose une page de test et de configuration qui peut vous générer le code JavaScript adéquat selon vos options.  Vous pourrez directement choisir les options et pré-visualiser directement la façon dont ce code va apparaître sur votre site web.

Ce configurateur est disponible à l’adresse suivante :

https://www.yammer.com/widget/configure

Voici un aperçu de ce configurateur :

Ca y’est, vous avez compris les bases de Yammer Embed ? Vous êtes maintenant prêt à suivre le chapitre suivant, où nous allons voir comment en quelques clics inclure un flux d’actualité Yammer dans une page SharePoint.

Inclure un flux Yammer dans une page SharePoint

Dans ce premier exemple, voyons comment inclure un flux de discussions Yammer au sein d’un site SharePoint. C’est un scénario très courant et pratique dans de nombreux cas.

Prenons quelques exemples pratiques de l’utilité de cette démarche :

1. Vous utilisez un site SharePoint de type « Site de publication » pour, par exemple, votre Intranet de communication. Vous pourriez par exemple vouloir inclure sur votre page d’accueil le flux de discussion du groupe Yammer géré par la communication interne ;
2. Vous utilisez un site Intranet, et vous souhaitez par exemple afficher sur la page d’accueil l’actualité de l’utilisateur sur réseau social (façon « Mon actualité sociale »). Cette approche vous permet de personnaliser et de « profiler » facilement l’expérience utilisateur sur un site Intranet ;
3. Vous utilisez un site Intranet, et vous souhaitez ajouter une zone d’échange entre vos collaborateurs. Par exemple, une zone « support » ou « aide » où les personnes pourraient poser des questions à un service spécifique ;
4. Vous utilisez un site SharePoint pour gérer les documents et les tâches d’une équipe et d’un projet. Vous pourriez par exemple inclure sur la page d’accueil un fil de discussion Yammer pour laisser les personnes mettre en avant les nouveautés du site, sans pour autant les obliger à naviguer sur le site Yammer pour ça ;
5. Etc. etc.

Pour inclure un flux Yammer d’un groupe au sein d’un site SharePoint 2013, vous pouvez suivre les étapes suivantes :

1 : Création d’un groupe Yammer

Vous devez au préalable créer un groupe dans Yammer ou utiliser un site existant. Cliquer ensuite sur le bouton « Intégrer ce groupe sur votre site » dans la widget de droite appelée « Options d’accès » (cf chapitre 1). Copier/Coller ensuite le code JavaScript affiché à l’écran.

2 : Editer une page de votre site SharePoint

Connectez-vous à votre site SharePoint. Naviguez sur la page dans laquelle vous souhaitez ajouter un flux de discussion.

Cliquer sur le « rouage » d’administration, puis sur le bouton « Modifier la page » :

3 : Insérer une WebPart de script

Placez-vous dans une zone d’édition de contenu. Dans le ruban SharePoint, cliquez sur l’onglet « Insérer ». Cliquez alors sur le bouton « Composant WebPart » :

Dans la liste des WebParts disponibles, sélectionnez la catégorie « Media et contenu », puis sélectionnez la WebPart nommée « Editeur de scripts ». Cliquer sur le bouton « Ajouter » : 

Une fois la WebPart insérée dans votre page, cliquez sur la flèche descendante en haut à droite de la WebPart, puis sur le bouton « Modifier le composant WebPart » :

Cliquez alors sur le bouton « Modifier l’extrait de code » :

4 : Insérer le code JavaScript Yammer Embed

Dans la zone d’édition qui apparaît à l’écran, copiez/collez le code Embed fournit par Yammer dans cette zone :

Astuce : C’est à ce moment que vous pouvez modifier le code JavaScript pour personnaliser la façon dont le flux Embed va apparaître sur votre site.

Dans le ruban SharePoint, cliquez sur « Enregistrer » pour enregistrer vos modifications et sortir du mode édition :

Et voilà, désormais votre flux Yammer apparaît sur la page de votre site SharePoint :

Maintenant vos utilisateurs pourront discuter, répondre, « aimer », notifier des utilisateurs, etc. directement depuis leur site SharePoint sans devoir changer d’interface. Yammer Embed offre une bonne expérience fonctionnelle, similaire à l’utilisation sur le site yammer.com.

En modifiant le code JavaScript que vous insérez dans vos pages, vous pourrez facilement inclure le flux d’un groupe, d’un utilisateur, ou encore d’un tag selon vos besoins. Vous pouvez également modifier la taille prise par ce flux de discussion, en modifiant les paramètres « width » (largeur) et « height » (hauteur) de la zone d’affichage.

Inclure un bouton « Like » dans une page SharePoint

Un autre scénario intéressant d’intégration de Yammer dans un site SharePoint est la possibilité d’inclure un bouton « Like » sur une page de votre Intranet. En effet, ceci est une fonctionnalité relativement populaire sur les sites Internet, via par exemple le bouton « J’aime » de Facebook.

On peut très facilement reproduire cette même fonctionnalité avec SharePoint et Yammer. Ceci peut vous permettre de donner plus de visibilité à vos contenus SharePoint. En « aimant » une page de votre Intranet, un utilisateur va le faire savoir sur le réseau social, permettant d’en informer les personnes qui le suivent et qui pourront alors aller lire la page publiée sur l’Intranet.

Pour insérer un bouton « Like » sur une page de SharePoint, vous pourriez procéder de deux façons différentes :

1. Insérer un code JavaScript Yammer Embed générique dans le gabarit d’une page de publication. Ceci n’est applicable que dans le cas où vous utilisez un site de publication. Cette technique a un avantage évident : chaque page qui sera créée à partir de ce gabarit bénéficiera automatiquement du bouton, sans effort additionnel ;
2. Insérer un code JavaScript Yammer Embed dans une WebPart de type « Editeur de script ». Ceci est équivalent, avec un code JavaScript différent, de la méthode utilisée dans l’exemple précédent ;

Quelle que soit la méthode que vous utilisez, pour ajouter un bouton « J’aime » sur une page de votre Intranet, vous pouvez utiliser le code JavaScript suivant : 

<div id="embedded-like"></div>
<script type="text/javascript" src="https://assets.yammer.com/assets/platform_js_sdk.js"></script>
<script type="text/javascript">
yam.connect.actionButton({
 container: "#embedded-like",
 network: "yournetwork.com",
 action: "like"
});
</script>

Avec ce code JavaScript, le bouton Like va apparaître sur votre page :

Ce bouton est capable de se « souvenir » de l’action d’un utilisateur : si celui-ci a déjà cliqué sur ce bouton sur une page, ce bouton apparaîtra avec la forme suivante :

L’utilisateur pourra alors annuler son action en recliquant sur le bouton.

Sur le réseau Yammer, les utilisateurs qui suivent l’utilisateur ayant cliqué sur le bouton, pourront voir cette action dans la widget « Activités récentes » disponible sur la page d’accueil. Une activité du type « Katie Jordan liked LeTitreDeMaPage » va apparaître. Au survol de la souris, on peut voir le détail de ce que la personne a aimé et cliquer sur l’adresse de la page pour y accéder :

Inclure un flux de commentaires dans vos pages

Une autre possibilité avec le kit JavaScript de Yammer, est le fait d’utiliser les flux de discussion de Yammer comme des zones de commentaires propres à chaque page. Contrairement à l’utilisation d’un flux pointant sur un groupe, les commentaires pourront être publiés par l’utilisateur dans le groupe de son choix.

Avec cette technique, vous pouvez collecter les retours de vos utilisateurs avec le meilleur des fonctionnalités de discussion, tout en bénéficiant des capacités de Yammer pour échanger sur un sujet (notification, ciblage d’un groupe, etc.). Un autre avantage sera également que les commentaires réalisés sur une page seront relayés sur le réseau social.

Comme pour le bouton « J’aime », deux techniques peuvent être utilisées pour insérer un flux de commentaires sur des pages d’un Intranet : via un code inséré dans le gabarit des pages, ou directement dans une page via une WebPart dite de type « Editeur de scripts ».

Pour inclure une zone de commentaires dans une page SharePoint, vous pouvez utiliser le code JavaScript suivant : 

<div id="embedded-feed" style="width: 800px; height: 450px;"></div>
<script type="text/javascript" src="https://assets.yammer.com/assets/platform_js_sdk.js"></script>
<script type="text/javascript">
    yam.connect.embedFeed({
        container: "#embedded-feed",
        feedType: "open-graph",
        config: {
            promptText: "Commenter cet article",
            header: false,
            footer: false
        }
    });
</script>

Avec cet exemple de code, la zone de commentaire de ce type va être affichée sur votre site SharePoint :

Dans la zone de rédaction d’un commentaire, l’avantage d’utiliser Yammer est que l’utilisateur va pouvoir bénéficier des fonctionnalités de notification d’un groupe ou d’un utilisateur :

Enfin, on peut noter que les commentaires réalisés dans ces zones respectent les principes de sécurité de Yammer. Ceci veut dire que lorsqu’un commentaire est publié dans un groupe privé de Yammer, seuls les utilisateurs ayant accès à ce groupe pourront voir ces commentaires depuis la page SharePoint.

Astuce 1 : Il faut noter que si vous souhaitez utiliser plusieurs composants à la fois (exemple : bouton J’aime + zone de commentaires, vous ne devez inclure qu’une seule fois le code appelant la librairie JavaScript de Yammer.

Astuce 2 : Il est important de noter qu’avec Yammer Embed, le code HTML de la balise « div » (zone d’affichage) doit obligatoirement se trouver AVANT le code JavasScript. Dans le cas contraire, cela ne marchera pas.

Pour aller plus loin

Si vous êtes amateur de JavaScript, il faut également savoir que l’on peut exécuter du code après certains évènements déclenchés par le composant Yammer Embed.

Vous pourrez par exemple exécuter du code personnalisé après que le fil de discussion se soit chargé sur la page.

Pour connaître les capacités de gestion des évènements via du code JavaScript, vous pouvez lire la page de documentation suivante :

https://developer.yammer.com/v1.0/docs/feed-events

Conclusion

Yammer Embed est un moyen simple et rapide, avec un minimum de code, d'inclure des fonctionnalités sociales de Yammer au sein de sites SharePoint. Elles peuvent vous permettre, dans n’importe quel type de site, d’inclure des fils de discussions provenant de groupes, d’utilisateurs, de tags ou encore d’ajouter des boutons « J’aime » et des zones de commentaires.

On peut également noter que Yammer Embed n’utilise que des méthodes dites « côté client » (exécutées par le navigateur de l’utilisateur) et donc très peu intrusives vis-à-vis de la technologie sous-jacente. Pour cette raison, les techniques démontrées peuvent être aussi bien utilisées sur SharePoint Online que sur SharePoint Server.

Pour utiliser Yammer Embed avec SharePoint, deux fonctionnalités importantes sont à connaître : l’utilisation de WebParts dites « Editeur de scripts », ou alors le principe des gabarits de page (pour les sites de publication uniquement).

Cet article est un aperçu simple des capacités d’intégration des deux produits. Nous avons vu comment intégrer des informations provenant de Yammer au sein de SharePoint (et non le contraire). Pour information, on peut également concevoir des scénarii plus complexes d’intégration en utilisant l’API REST et le SDK JavaScript de Yammer, mais cela pourrait faire l’objet d’un autre article à part entière.

Enjoy Yammer & SharePoint !

Preface

Welcome to the third and last chapter of this section dedicated to the integration of the Office Graph API within a .net Windows Phone 8.1 application and Cortana. In the previous chapters, we have seen how interrogate in C# and XML the Office Graph to find elements of its network, connecting securely to Azure Active Directory through the ADAL library. We could find elements of the graph and display to browse through them.

You can DOWNLOAD THE SOURCE CODE in the joined ZIP file, available at the end of each chapter.

This article is published to the TechDays 2015, which will take place from 10 to 12 January 2015 to the Palais des Congrès de Paris. This year I would have the chance to co-animate the session dedicated to Office Graph with Alexandre Cipriani and Stéphane Palluet. Enjoy many of our session for this example and many more.

For this chapter, I want to thank Steve Peschka. Much of the code used here is inspired by his example "CloudTopia" which was presented at numerous events. I recommend more than strongly reading his blog post. 

Steve is a source of incredible information, thanks a lot.

Chapter 1: Introduction to the Office Graph

Chapter 2: How to make queries by code to the Office Graph?

Chapter 3: Integration with Cortana (this article)

About the Cortana API

In this last section, we will now focus to how drive our research on the graph through voice commands. Since a few weeks in France on Windows Phone 8.1, it is now possible to control his phone with the voice, thanks to the Cortana. Cortana is a true voice recognition interface, allowing to speak with his phone to steer its applications.

In this example, we will use the SDK of Cortana to achieve controls that will know naturally ask our business graph, as shown in the following schema:

When you develop an application for Cortana, can use two types of components:

• Speech recognition kit (SpeechRecognition namespace) :  allows to listen to the user, understand the phrases and words as he speaks.
• Speech synthesis kit (SpeechSynthesis namespace) :  allows to talk with Cortana's voice, so for example our application to respond to user commands.

In addition to the integration of these two components, we will see that we also instruct Cortana how automatically launch our application, interpreting the command to open at the same time.

About voice commands

To query the Office Graph vocally, we could for example ask the application to display documents about its social graph axes. These axes could be persons of his circle, his manager, the popular elements around itself, the documents that we've read, etc. etc.

In this example, we will rely vocal instruction, which will allow us to understand what is the axis that wants to see the user. We can examine the graph with controls detailed in the table below. It is important to understand that each of these commands has one or more words that will be detected in a sentence to launch the command:

Now let's see how to implement these orders with Cortana and voice APIs of Windows Phone.

Cortana main classes

To use Cortana, we must include two namespaces corresponding to speech recognition and synthesis libraries:

using Windows.Media.SpeechRecognition;
using Windows.Media.SpeechSynthesis;

How to learn to Cortana to speech words and phrases ?

We'll start with the SpeechSynthesis part, to talk about Cortana, allowing him to answer us at voice commands.

To do this, we first initialize an object of type SpeechSynthesizer. During this initialization, can specify what type of voice and the language used by the speech engine. In our example we will for example choose to use the female voice and the English language, with the following code:

SpeechSynthesizer Synthesizer = new SpeechSynthesizer();
foreach (var voice in SpeechSynthesizer.AllVoices)
{
    if (voice.Gender == VoiceGender.Female && voice.Language.ToLowerInvariant().Equals("en-us"))
    {
        Synthesizer.Voice = voice;
    }
}

With the synthesizer object, we can get him to say phrases in English. We use two different ways:

• Phrases as simple strings, without any form of formatting through the SynthesizeTextToStreamAsync method;
• Phrases formatted at the SSML (XML format) format through the SynthesizeSsmlToStreamAsync method. The advantage of this format is that you can for example control the level of intonation of voice over this or that Word;

Consider the following example to say to Cortana  "Sorry, I did not understand " when we fail to understand the command launched by the user.

In SSML, can represent the sentence in the following way to accentuate the intonation of the word "sorry":

<speak version='1.0' xmlns='http://www.w3.org/2001/10/synthesis' xml:lang="en-US">
  <prosody pitch='+35%' rate='-10%'> Sorry</prosody>
  <prosody pitch='-15%'> I did not understand.</prosody>
</speak>

Simply write the following code method giving in argument the string containing the SSML formatted text :

public async void StartSpeakingSsml(string ssmlToSpeak)
{
    // Generate the audio stream from plain text.
    SpeechSynthesisStream stream = await this.Synthesizer.SynthesizeSsmlToStreamAsync(ssmlToSpeak);
    // Send the stream to the media object.
    var mediaElement = new MediaElement();
    mediaElement.SetSource(stream, stream.ContentType);
    mediaElement.Play();
}

Recognize the voice command 

Now we've seen start do talk about Cortana, let's look at how to ensure that Cortana listens to the words and how to interpret them by code.

The first step is to initialize the SpeechRecognizer object, that will serve us to start listening to the command.With this object, we can also define a method which will be executed when the listen operation is completed.

Listening status is returned via the AsyncStatus type argument that indicates the result (Completed or Error).The text as a string is returned via the GetResults method which returns us an object of type SpeechRecognitionResult.

In the example below, we will for example initialize the SpeechRecognizer, then set the code that will be executed upon receipt of voice control. If the status is good, we retrieve the contents of the text and let's look at the text contains the keywords "my work". If this is the case, we will load method which will call the Office Graph on the current user work  (LoadMyWork). Otherwise we will call a method which will talk about Cortana to indicate that the command has not been understood.

.

private async void InitializeRecognizer()
{
    this.Recognizer = new SpeechRecognizer();
    SpeechRecognitionTopicConstraint topicConstraint
        = new SpeechRecognitionTopicConstraint(SpeechRecognitionScenario.Dictation, "Work");

    this.Recognizer.Constraints.Add(topicConstraint);
    await this.Recognizer.CompileConstraintsAsync(); // Required

    recoCompletedAction = new AsyncOperationCompletedHandler<SpeechRecognitionResult>((operation, asyncStatus) =>
    {
        Dispatcher.RunAsync(Windows.UI.Core.CoreDispatcherPriority.Normal, () =>
        {
            this.CurrentRecognizerOperation = null;
            this.SearchTextBox.Text = "Listening your command";

            switch (asyncStatus)
            {
                case AsyncStatus.Completed:
                    SpeechRecognitionResult result = operation.GetResults();
                    if (!String.IsNullOrEmpty(result.Text))
                    {
                        string res = result.Text.ToLower();
                        				
                        if (res.Contains("my work"))
                            LoadMyWork();
                        else
                            speechHelper.WrongCommand();
                    }
                    break;
                case AsyncStatus.Error:
                    speechHelper.WrongCommand();
                    break;
                default:
                    break;
            }
        }).AsTask().Wait();
    });
}

We will now look at how to start listening to Cortana in the application. At the click of a button (the microphone in our case), we will launch the active listening of Cortana. For this, we use the RecognizeAsync method, specifying the method which will be called when the listen operation will be completed: 

private void StartListening()
{
    try
    {
        beepStart.Play();
        this.SearchTextBox.Text = "Listening...";

        // Start listening to the user and set up the completion handler for the result
        // this fires when you press the button to start listening 
        this.CurrentRecognizerOperation = this.Recognizer.RecognizeAsync();
        this.CurrentRecognizerOperation.Completed = recoCompletedAction;
    }
    catch (Exception)
    {
        beepStop.Play();
        recoCompletedAction.Invoke(null, AsyncStatus.Error);
    }
}

Let's see now how the application works:

Here, we are now able to launch voice commands via Cortana, understand the realized commands and launch the Office Graph based on the criteria selected by the user.

Now the best of all: allowing to start research on the Office Graph without even manually start the application My Office Graph!

How to use Cortana to start directly our voice commands?

It is one of the most impressive features of Cortana: its ability to learn new commands through the applications installed on the phone.

When an application uses this feature, the user has the ability to send voice commands to an application directly from the main interface of Cortana. Cortana will open the application and 'send' the identified voice command. Cortana will be able to understand that any order concerning such application, thanks to a system of prefixes.

In our example, we will define starting his sentence with "Office Graph", Cortana can know whether a specific command to the Office Graph and start the My Office Graph application. It will also analyze the text after the words "Office Graph" to detect a built-in command and run this command within the application.

We could define the following commands to start queries: "Office Graph my work», «Office Graph, search the shared items», etc. etc.

To do this, we need to set up a voice command file, which is a file in the XML format that is included in the application. This file will contain the prefix from the application, as well as the different commands. Different commands will define the sample text, the words listened to, be they voluntary or mandatory:

<?xml version="1.0" encoding="utf-8"?>

<!-- Be sure to use the new v1.1 namespace to utilize the new PhraseTopic feature -->
<VoiceCommands xmlns="http://schemas.microsoft.com/voicecommands/1.1">
    
  <CommandSet xml:lang="en-us" Name="officeGraphCommandSet">
    <!-- The CommandPrefix provides an alternative to your full app name for invocation -->
    <CommandPrefix> Office Graph </CommandPrefix>
    <!-- The CommandSet Example appears in the global help alongside your app name -->
    <Example> load my work </Example>

    <Command Name="popular">
      <Example> popular documents </Example>
      <ListenFor>[Display] [Find] [Search] popular [elements] [items] [documents]</ListenFor>
      <Feedback>Search popular items in progress...</Feedback>
      <Navigate  />
    </Command>
...

To load the voice commands into Cortana, can execute the method below during initialization of the application.This method will install the commands contained in the VoiceCommandDefinition_8.1.xml file  in the App package:

/// <summary>
/// Install the voice commands
/// </summary>
private async void InstallVoiceCommands()
{
    const string wp81vcdPath = "ms-appx:///VoiceCommandDefinition_8.1.xml";

    Uri vcdUri = new Uri(wp81vcdPath);
    StorageFile file = await StorageFile.GetFileFromApplicationUriAsync(vcdUri);
    await VoiceCommandManager.InstallCommandSetsFromStorageFileAsync(file);
}

Once the order has been installed, the application is visible from "See more samples" screen inside hte Cortana interface. To check this, we simply open Cortana (in button on the phone for example search button), down everything at the bottom to see the installed applications using Cortana, click on our app «My Office Graph» and the list of examples of available commands is displayed:

Now that the controls are installed, Cortana will be able to recognize our command during a speech, summarize the order included and then launch the application. The following screenshots show the process for the user:

When Cortana will launch our application, we will be notified in the code via our App OnActivated event. Cortana will send us an argument of type "VoiceCommand" for which we will be able to know the name of the detected command and eventually the page that must be opened with this command:

protected override void OnActivated(IActivatedEventArgs args)
{
// When a Voice Command activates the app, this method is going to 
// be called and OnLaunched is not. Because of that we need similar
// code to the code we have in OnLaunched
// For VoiceCommand activations, the activation Kind is ActivationKind.VoiceCommand
if (args.Kind == ActivationKind.VoiceCommand)
{
  // since we know this is the kind, a cast will work fine
  VoiceCommandActivatedEventArgs vcArgs = (VoiceCommandActivatedEventArgs)args;

  // The NavigationTarget retrieved here is the value of the Target attribute in the
  // Voice Command Definition xml Navigate node
  string voiceCommandName = vcArgs.Result.RulePath.First();
  string target = vcArgs.Result.SemanticInterpretation.Properties["NavigationTarget"][0];
…
}
}

We are able now to see our social graph of business in a few seconds thanks to the voice. We are able to know the news of its network in the Organization and do not miss any document, presentation, excel or even video published around us!!!

We have seen that it is simple to query his business graph and integrate it into a third-party application. The Office Graph is powerful and offers us a great way to integrate a social dimension to any enterprise application.

We could, with the same principles as those detailed in this article, display in an App or an Intranet site a large number of information to assist the end-user to find or identify in seconds.

Thank you for your interest for this article, and have fun with the Office Graph!

MyOfficeGraph-20150113.zip

Preface

Welcome to the second chapter of this section dedicated to the integration of the Office Graph API within an application .net Windows Phone 8.1 and Cortana. In the previous chapter, we saw what is the syntax to call web services and to achieve its company graph results. In this chapter, we will now see how to connect to the Office Graph and perform queries in .net.

You can DOWNLOAD THE SOURCE CODE in the joined ZIP file, available at the end of each chapter.

This article is published to the TechDays 2015, which will take place from 10 to 12 January 2015 to the Palais des Congrès de Paris. This year I would have the chance to co-animate the session dedicated to Office Graph with Alexandre Cipriani and Stéphane Palluet. Enjoy many of our session for this example and many more. 

Chapter 1: Introduction to the Graph Office

Chapter 2: How to make queries by code to the Office Graph? (this article)

Chapter 3: Integration with Cortana

Prerequisites

In our example, we will use three major technical components, which can be represented by the following schema:

More details about these components:

1. ADAL (Active Directory Authentication Library): is a library to support authentication to the Azure Active Directory underlying Office 365. ADAL will bring us the flexibility to be able to authenticate the user to securely, without storing the login / password for the user. It will allow to rest on the oAuth authentication concepts, with levels specific and transparent access to your data.
2. Office Graph API: as detailed in the previous article, this is the entry point of the web services that will allow us to browse the social graph
3. Windows Phone 8.1 Store Apps & Cortana SDK: allow us to easily develop an application with an interface written in XAML c#, easily compatible with Windows 8.1. It will also allow to define and capture voice commands to query the Office Graph to the voice.

To develop the App, we will need on our workstation :

• Visual Studio 2013
• Visual Studio 2013 Update 4
• Windows Phone 8.1 SDK

These components are installed with most versions of Visual Studio, or in free express version at the following address:

https://dev.windows.com/en-us/develop/download-phone-sdk

Last important point, we need a Windows Phone 8.1 or an emulator (included in the SDK) containing Windows Phone 8.1 with the Cortana feature.

Visual Studio project template

To create a Windows Phone project 8.1 using Cortana and the Office Graph, you can choose the model of project of type Windows Phone Apps in the "Apps Store" section. This type of application, appeared with Windows 8.1 and Windows Phone 8.1, allows us to create applications that aren't in Silverlight, well written in XAML:

Authentication with ADAL

To be able to perform queries on the Office Graph, we must be first authenticated. To do this, we can retrieve an Azure Active Directory authentication token, that we can provide to our requests.

With Azure Active Directory, it is possible to easily create an application that can benefit from existing authentication systems to the platform. For example, we will not have to store the login / password for the user: we will leave Azure to certify and support authentication.

Install ADAL in your Visual Studio solution

To simplify the task of the developer, Microsoft has created ADAL (Active Directory Authentication Library), which is a code library available on many platforms (.Net, Javascript, Cordova, Xamarin, etc.). This library will allow to simply add an authentication process in our application.

To use ADAL, you need to first import the library into our solution. The process is very simple thanks to the Visual Studio nuggets system .

The ADAL package is available at the following address:

https://www.nuget.org/packages/Microsoft.IdentityModel.Clients.ActiveDirectory/

You can install it in your Visual Studio solution using the following command:

Declare the Application in Azure

To be able to communicate with Azure Active Directory, we need to declare a new app in our Azure tenant. Declare an application in Azure returns to save the information of our application and get in return a key called "ClientId" which will serve us within our application.

This can be done by several ways:

• the Azure management portal: The full procedure to register an application is detailed on the following article: http://azure.microsoft.com/en-us/documentation/articles/mobile-services-windows-store-dotnet-adal-sso-authentication/
• Use the interface of Visual Studio to register the Application for you, thanks to the Office 365 SDK extension. In fact, if you install this extension in Visual Studio, you can add to your App a "Connected Service" as Office 365, which comes with a Wizard for the automatic registration of Apps in Azure.This procedure is described in detail in the following link: http://msdn.microsoft.com/en-us/office/office365/howto/adding-service-to-your-Visual-Studio-project

The 2nd technical is relatively simple. To use it, you simply need to download the Office 365 extensions for Visual Studio 2013, from here:

https://aka.ms/OfficeDevToolsForVS2013

Once installed, simply right click on your Visual Studio solution, and then click on "Add", then "Connected Service":

You can then access the Services Manager that allows to manage Office 365 services. You can login with your account Office 365 for save your App on your holding of company:

With this wizard, you can select the levels of approval required to the application on the different  Office 365 resources. To read the Office Graph, we have at least read permissions on the 'My Files' and 'Sites '. Just click on the service name, and then select the right of reading: 

When you post the window, Visual Studio will save your application in Azure, as you would via the  Azure management portal. It will also insert the keys needed to your application (such as the ClientId or authentication authority) in App settings. In the case of a Windows Phone 8.1 App Store, the parameters are automatically inserted in the App.xaml file, as a resource of the application, as for example:

<Application.Resources>
    <x:String x:Key="ida:ClientID">b53a731a-2638-49a9-8122-1bc9ea233995</x:String>
    <x:String x:Key="ida:AuthorizationUri">https://login.windows.net</x:String>
...
</Application.Resources>

Manage the connection in c# .net

Now that we have seen how to register the App, we are ready to implement the authentication ADAL system in our .Net classes.

To use ADAL in our classes, we need to include the following namespaces:

using Microsoft.IdentityModel.Clients.ActiveDirectory;
using Windows.Security.Authentication.Web;

To add support for authentication to a page, we must prepare this page to manage the recovery process.Following authentication with Azure, we will have a return to our application that can continue treatment. To simply implement this principle, we can create the IWebAuthenticationContinuable interface, and it will suffice to inherit our page of this interface:

/// <summary>
/// Implement this interface if your page invokes the web authentication
/// broker
/// </summary>
interface IWebAuthenticationContinuable
{
    /// <summary>
    /// This method is invoked when the web authentication broker returns
    /// with the authentication result
    /// </summary>
    /// <param name="args">Activated event args object that contains returned authentication token</param>
    void ContinueWebAuthentication(WebAuthenticationBrokerContinuationEventArgs args);
}
public sealed partial class MainPage : Page, IWebAuthenticationContinuable 
{
…

Within our page, authentication will be supported through the AuthenticationContext class, which allows you to create an authentication context to an authority, and to negotiate the tokens acquisition.

AuthenticationContext ac = null;

To create the context, we will need to provide to ADAL the redirection address for our application. This address is a specific address, but can be easily acquired by the method GetCurrentApplicationCallbackUri of the WebAuthenticationBroker  class, like this:

Uri RedirectUri = WebAuthenticationBroker.GetCurrentApplicationCallbackUri();

We also provide authentication authority. With Office 365 and Azure Active Directory, the address is of this kind :  « https://login.windows.net/<yourtenantdomain> » 

string Authority = "https://login.windows.net/yourtenantdomain.com";

If you use the Office 365 SDK to reference your application, you can retrieve the key from resource with the following syntax:

string Authority = App.Current.Resources["ida:AuthorizationUri"].ToString() + "/ yourtenantdomain.com ";

The last parameter to provide for authentication is client key of your application that we generated in the previous section. This key is in the form of a GUID:

string ClientID = "[your-app-id as for example ‘b6ea739a-2608-4919-8123-12asd233b65’";

If you use the Office 365 SDK to reference your application, you can retrieve the client ID from the resources key with the following syntax:

 string ClientID = App.Current.Resources["ida:ClientID"].ToString();

To initialize the context, you must use the CreateAsync method on the page OnNavigatedTo event:

/// <summary>
/// Invoked when this page is about to be displayed in a Frame.
/// </summary>
/// <param name="e">Event data that describes how this page was reached.
/// This parameter is typically used to configure the page.</param>
protected override void OnNavigatedTo(NavigationEventArgs e)
{
      ac = AuthenticationContext.CreateAsync(Authority).GetResults();
}

We also need to implement the method allowing the resumption of activity following the redirect. To do this, we add the following code:

public async void ContinueWebAuthentication(Windows.ApplicationModel.Activation.WebAuthenticationBrokerContinuationEventArgs args)
{
      await ac.ContinueAcquireTokenAsync(args); 
}

Now create the Login method that will be called when the user clicks on the button "Login" from our interface.The Login method will first try to acquire the token for authentication of "silently". This means that we try to authenticate us without calling the interface connection. If the user is already logged in, we will have its cached token and may give access directly. This is possible through the call to the method AcquireTokenSilentAsync of the AuthenticationContext object.

private async void Login()
{
      AuthenticationResult result = await ac.AcquireTokenSilentAsync(Resource, ClientID);
      if (result != null && result.Status == AuthenticationStatus.Success)
          LoadApp(result);
      else
          ac.AcquireTokenAndContinue(Resource, ClientID, RedirectUri, LoadApp);
}

private void LoadApp(AuthenticationResult ar)
{
     var AuthToken = ar.AccessToken;
     this.Frame.Navigate(typeof(CortanaPage), AuthToken);
}

If the authentication result is not successful, we will call the AcquireTokenAndContinue method, which will redirect the user to the graphical interface for authentication of its holding. The experience of connection will take place in 2 to 3 times: before the login, enter the password (separate from the login if the tenant uses a redirect SSO), acceptance of the terms of use, then redirection to our application:

When the identification is completed, the result of authentication (via the AuthenticationResult class) contains the token authentication via the AccessToken property. We can use token in our REST of the office Graph queries. 

How to query the Office Graph in C# and XML

Now that we have recovered our authentication token, we can generate http query on the Office Graph.

To do this, add the following namespaces:

using System.Net.Http;
using System.Net.Http.Headers;

We will use the HttpClient class to perform queries. Take a few simple examples.

Example 1: find the actor ID of your manager

To find items from our manager, we need first to find his Actor ID. We can make the following query by providing the authentication token. After reading the result, we can easily get a list of results and retrieve column 'DocId' (which is the Actor ID in Office Graph):

String query = "https://<your-tenant-url>/_api/search/ query?Querytext=%27*%27&Properties=%27GraphQuery:ACTOR(ME\\,action\\:1013)%27&SourceId=%27b09a7990-05ea-4af9-81ef-edfab16c4e31%27&SelectProperties=%27UserName,DocId%27";
HttpClient httpClient = new HttpClient();
httpClient.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", AuthToken);
httpClient.DefaultRequestHeaders.Accept.Add(new MediaTypeWithQualityHeaderValue("application/atom+xml"));
HttpResponseMessage response = await httpClient.GetAsync(query);
if (response.IsSuccessStatusCode)
{
     Stream resultStream = response.Content.ReadAsStreamAsync().Result;

      // process response..
      XDocument oDataXML = XDocument.Load(resultStream, LoadOptions.None);
      XNamespace atom = "http://www.w3.org/2005/Atom";
      XNamespace d = "http://schemas.microsoft.com/ado/2007/08/dataservices";
      XNamespace m = "http://schemas.microsoft.com/ado/2007/08/dataservices/metadata";

      List<XElement> items = oDataXML.Descendants(d + "query")
                                             .Elements(d + "PrimaryQueryResult")
                                             .Elements(d + "RelevantResults")
                                             .Elements(d + "Table")
                                             .Elements(d + "Rows")
                                             .Elements(d + "element")
                                             .ToList();
      var searchResults = from item in items
         select new
         {
         DocId = item.Element(d + "Cells").Descendants(d + "Key").First(a => a.Value == "DocId").Parent.Element(d + "Value").Value
         };

}

In this sample, searchResults contains the list of the players returned by the query.

Example 2: find popular elements around you (as the Delve home page)

Are now trying to reassemble all the popular elements around us, as is the case on the homepage of Delve. The method is identical to the previous example, but this time we will operate the properties related to documents such as the title, the way, the extension, the parent site, etc.

string query = "https://<your-tenant-url>/_api/search/query?QueryTemplate=%27((NOT%20HideFromDelve%3ATrue)%20AND%20(FileExtension%3Adoc%20OR%20FileExtension%3Adocx%20OR%20FileExtension%3Appt%20OR%20FileExtension%3Apptx%20OR%20FileExtension%3Axls%20OR%20FileExtension%3Axlsx%20OR%20FileExtension%3Apdf%20OR%20ContentTypeId%3A0x010100F3754F12A9B6490D9622A01FE9D8F012*%20OR%20contentclass%3AExternalLink))%27&Properties=%27TitleBasedSummaries%3Atrue,IncludeExternalContent%3Atrue,GraphQuery%3Aand(actor(me%5C%2Caction%5C%3A1021)%5C%2Cactor(me%5C%2Cor(action%5C%3A1021%5C%2Caction%5C%3A1036%5C%2Caction%5C%3A1037%5C%2Caction%5C%3A1039%5C%2Caction%5C%3A1052%5C%2Caction%5C%3A1048))),GraphRankingModel%3Aaction%5C%3A1021%5C%2Cweight%5C%3A1%5C%2CedgeFunc%5C%3Aweight%5C%2CmergeFunc%5C%3Amax%27&SelectProperties=%27Author,AuthorOwsUser,ContentClass,ContentTypeId,DefaultEncodingURL,DocId,DocumentPreviewMetadata,Edges,EditorOwsUser,FileExtension,FileType,HitHighlightedProperties,HitHighlightedSummary,LastModifiedTime,LikeCountLifetime,ListID,ListItemID,MediaDuration,OriginalPath,Path,PictureThumbnailURL,PrivacyIndicator,Rank,SPWebUrl,SecondaryFileExtension,ServerRedirectedPreviewURL,ServerRedirectedURL,SitePath,SiteTitle,Title,ViewCountLifetime,siteID,uniqueID,webID%27&RankingModelId=%270c77ded8-c3ef-466d-929d-905670ea1d72%27&RowLimit=36&ClientType=%27PulseWeb%27&BypassResultTypes=true&EnableQueryRules=false&ProcessBestBets=false&ProcessPersonalFavorites=false";
HttpClient httpClient = new HttpClient();
httpClient.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", AuthToken);
httpClient.DefaultRequestHeaders.Accept.Add(new MediaTypeWithQualityHeaderValue("application/atom+xml"));
HttpResponseMessage response = await httpClient.GetAsync(query);
if (response.IsSuccessStatusCode)
{
     Stream resultStream = response.Content.ReadAsStreamAsync().Result;

      // process response..
      XDocument oDataXML = XDocument.Load(resultStream, LoadOptions.None);
      XNamespace atom = "http://www.w3.org/2005/Atom";
      XNamespace d = "http://schemas.microsoft.com/ado/2007/08/dataservices";
      XNamespace m = "http://schemas.microsoft.com/ado/2007/08/dataservices/metadata";

      List<XElement> items = oDataXML.Descendants(d + "query")
                                             .Elements(d + "PrimaryQueryResult")
                                             .Elements(d + "RelevantResults")
                                             .Elements(d + "Table")
                                             .Elements(d + "Rows")
                                             .Elements(d + "element")
                                             .ToList();

            var graphResults = from item in items
    select new 
    {
        Title = item.Element(d + "Cells").Descendants(d + "Key").First(a => a.Value == "Title").Parent.Element(d + "Value").Value,
        Author = item.Element(d + "Cells").Descendants(d + "Key").First(a => a.Value == "Author").Parent.Element(d + "Value").Value,
        HitHighlightedSummary = item.Element(d + "Cells").Descendants(d + "Key").First(a => a.Value == "HitHighlightedSummary").Parent.Element(d + "Value").Value,
        Path = item.Element(d + "Cells").Descendants(d + "Key").First(a => a.Value == "Path").Parent.Element(d + "Value").Value,
        Ext = "Assets/Ext/" + item.Element(d + "Cells").Descendants(d + "Key").First(a => a.Value == "SecondaryFileExtension").Parent.Element(d + "Value").Value + ".png",
        ViewCount = item.Element(d + "Cells").Descendants(d + "Key").First(a => a.Value == "ViewCountLifetime").Parent.Element(d + "Value").Value,
        ServerRedirectedURL = item.Element(d + "Cells").Descendants(d + "Key").First(a => a.Value == "ServerRedirectedURL").Parent.Element(d + "Value").Value,
        ServerRedirectedPreviewURL = item.Element(d + "Cells").Descendants(d + "Key").First(a => a.Value == "ServerRedirectedPreviewURL").Parent.Element(d + "Value").Value,
        SiteTitle = item.Element(d + "Cells").Descendants(d + "Key").First(a => a.Value == "SiteTitle").Parent.Element(d + "Value").Value,
        UniqueID = item.Element(d + "Cells").Descendants(d + "Key").First(a => a.Value == "uniqueID").Parent.Element(d + "Value").Value,
        SiteID = item.Element(d + "Cells").Descendants(d + "Key").First(a => a.Value == "siteID").Parent.Element(d + "Value").Value,
        SiteUrl = item.Element(d + "Cells").Descendants(d + "Key").First(a => a.Value == "SPWebUrl").Parent.Element(d + "Value").Value,
        WebID = item.Element(d + "Cells").Descendants(d + "Key").First(a => a.Value == "webID").Parent.Element(d + "Value").Value
    };
}

How to get the documents thumbnails

In the interface of Delve, most displayed documents have thumbnails with a visual overview of the element. Develop such a feature 'from' scratch could be tedious, but once again the Office Graph API just help us.

To generate a PNG thumbnail of a document  you can call an address that will generate us a picture (when possible). We can call the following address with the parameters indicating the file and context information (UniqueID, WebID and SiteID):

var httpClient = new HttpClient();
httpClient.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", AuthToken);
var contentBytes = await httpClient.GetByteArrayAsync(DocumentPreviewImage);

We could then display this image in a control of type Image by writing the contents of the image in an object of type BitmapImage:

var ims = new InMemoryRandomAccessStream();
var dataWriter = new DataWriter(ims);
dataWriter.WriteBytes(contentBytes);
await dataWriter.StoreAsync();
ims.Seek(0);
BitmapImage bitmap = new BitmapImage();
bitmap.SetSource(ims);

Display the graph results in a ListBox

Now that we have seen how to retrieve the results of the Office Graph, as well as the miniatures of the documents, we can display them on a XAML page.

For this, we used in this example a ListBox to display the results as a list, one below the other.

To display the fields of the items returned by the Office Graph, we can for example use the command {{Binding Title}} to automatically display the corresponding property of the object.

We can also use the control MenuFlyout to display a shortcut menu on each item select long.

The code of our XAML view could be formed as follows:

<!--TODO: Content should be placed within the following grid-->
<Grid Grid.Row="1" x:Name="ContentRoot" Margin="19,9.5,19,0">
    <Grid.Resources>
        <DataTemplate x:Name="resultListTemplate">
            <StackPanel Holding="StackPanel_Holding" >
                <FlyoutBase.AttachedFlyout>
                    <MenuFlyout>
                        <MenuFlyoutItem Text="Ouvrir" />
                        <MenuFlyoutItem Text="Ouvrir le site" />
                        <MenuFlyoutItem Text="Envoyer par email" />
                        <MenuFlyoutItem Text="Partager sur Yammer" />
                    </MenuFlyout>
                </FlyoutBase.AttachedFlyout>
                <Grid Loaded="Grid_Loaded" Background="#FFFFFEFE" Margin="0,0,0,10">

                    <Grid.RowDefinitions>
                        <RowDefinition Height="Auto" />
                        <RowDefinition Height="Auto" />
                        <RowDefinition Height="Auto" />
                        <RowDefinition Height="Auto" />
                        <RowDefinition Height="Auto" />
                    </Grid.RowDefinitions>

                    <Grid.ColumnDefinitions>
                        <ColumnDefinition Width="*" />
                    </Grid.ColumnDefinitions>

                    <TextBlock Grid.Row="0" Grid.Column="0" TextWrapping="Wrap"
                                    Text="{Binding Title}" 
                                    Foreground="Black" FontSize="30" Height="Auto" Margin="5"  />

                    <Image  Grid.Row="1" Grid.Column="0"
                                    Stretch="UniformToFill" 
                                    Source="{Binding DocumentPreviewImage}" Loaded="Image_Loaded" Margin="5" />

                    <TextBlock Grid.Row="2" Grid.Column="0" TextWrapping="Wrap"
                                    Text="{Binding Author}" 
                                    Foreground="Gray" FontSize="20" Height="Auto" Margin="5"/>

                    <StackPanel Grid.Row="3" Grid.Column="0" Orientation="Horizontal" Margin="5" HorizontalAlignment="Right">
                        <TextBlock
                                    Text="{Binding ViewCount}"
                                    Foreground="Gray" FontSize="20" />
                        <TextBlock Text=" vues" Foreground="Gray" FontSize="20"></TextBlock>

                    </StackPanel>

                    <StackPanel Grid.Row="4" Grid.Column="0" Orientation="Horizontal" Margin="5">
                        <Image 
                                    Width="32" Height="32" Stretch="UniformToFill" 
                                    Source="{Binding Ext}"/>
                        <TextBlock TextWrapping="Wrap"
                                    Text=" - " 
                                    Foreground="Gray" FontSize="20" Height="Auto"/>
                        <TextBlock
                                    Text="{Binding SiteTitle}"
                                    Foreground="Blue" FontSize="20" />

                    </StackPanel>

                </Grid>
            </StackPanel>

        </DataTemplate>
    </Grid.Resources>

    <!-- actual list content goes here -->
    <ListBox Name="ResultsList" Grid.Row="0" 
                    ItemTemplate="{StaticResource resultListTemplate}" 
                    ItemsSource="{Binding}" Background="#FF0086D8" FontFamily="Global User Interface">
        <ListBox.ItemContainerStyle>
            <Style TargetType="ListBoxItem">
                <Setter Property="HorizontalContentAlignment" Value="Stretch"/>
            </Style>
        </ListBox.ItemContainerStyle>
    </ListBox>

</Grid>

With this sample code, we are able to display the elements as vignettes like the interface of Delve. When the user long clicks an item context menu will allow to perform certain actions on the element, as shown in the following screenshots:

If we click on the menu items, you can:

• Open the document in web mode (Internet Explorer opened to the page corresponding to the address of the document with Office Online)
• Open with Internet Explorer the site containing the document
• Create a mail to be sent containing the address of the document to share
• Share the link of the document within a Yammer group

To share content in Yammer, the operation is actually easier than others. In fact, Yammer has an address dedicated to applications for recommending content.

To display a Yammer sharing window, it is just that we open a page with the address formatted as follows:

For example, the address bing.com sharing will display us the sharing window shown below, allowing us to share the link with groups and colleagues:

We have seen in this chapter how to query the Office Graph in c# .net within a Windows Phone 8.1 application.We are now able to perform queries to display elements of the graph. We are also able to get the essential properties of the documents as well as a thumbnail picture. We just so more to 'connect' our calls to the Office Graph with voice commands of Cortana!

Go to the 3rd and final chapter of this article to read more:

Chapter 3: Integration with Cortana

MyOfficeGraph-20150113.zip