PI Services

Le blog des collaborateurs de PI Services

Exchange : Découverte de l'agent de scripting

Introduction

Depuis Exchange 2010, il existe les agents d'extension des Cmdlets. C'est une fonctionalité méconnue (car peu documentée) et pourtant très utile dans beaucoup d'entreprise.

Ces agents permettent d'étendre les fonctionnalités de base d'Exchange. Par exemple lors de la création d'une boîte aux lettres, si une base de données n'est pas renseignée alors un agent se charge d'en choisir une automatiquement. Quelque soit le mode d'administration (Powershell ou via la console graphique EMC), l'agent se lancera. Cela vient entre autre du fait que la console Exchange ne fait qu'exécuter du Powershell en tâche de fond. Il est possible d'obtenir la liste de ces agents en exécutant la Cmdlet suivante dans une session Powershell Exchange :

Voici le résultat obtenu sur une infrastructure sans paramétrage particulier de ces agents :

Exchange Extension Agent Listing

Il existe de nombreux agents ; notamment pour la gestion de l'OAB ou des boîtes aux lettres. Dans le résultat obtenu, 2 attributs vont nous intéresser : l'activation et la priorité. Le premier permet simplement de savoir si l'agent est actuellement utilisé ou non. Le second concerne l'ordre d'application. En effet, plusieurs agents peuvent agir sur la même chose (par exemple : le choix de la base de données pour une boîte aux lettres). La priorité permet de définir l'agent qui sera utilisé (celui qui a la priorité la plus basse, les autres ne seront pas utilisés). Pour changer la priorité d'un agent, il suffit d'utiliser la commande suivante :

L'agent qui nous intéresse dans cet article est le "Scripting Agent". Nous allons voir comment l'utiliser ainsi que quels exemples d'utilisation.

L'agent de script

A contrario des autres agents, l'agent de scripting est entièrement customisable par les administrateurs Exchange. Typiquement, il va nous permettre par exemple, de réaliser certaines actions au moment de la création d'une boîte aux lettres et donc de l'exécution de la commande New-Mailbox ou Enable-Mailbox (activer/désactiver POP3/Single item recovery etc, création d'une boîte d'archive, envoi d'un mail automatique à l'utilisateur). On peux aussi imaginer un export automatique de la boîte aux lettres au format PST lorsque la commande remove-mailbox sera lancée. D'autres types d'actions sont réalisables. Elles seront détaillées plus loin dans cet article. Tout type de script Powershell peux être intégré.

Par défaut l'agent de scripting n'est pas activé. C'est pourquoi, on utilise la commande :

Cette commande active l'agent de scripting sur tous les serveurs Exchange de l'organisation.

Attention : Le fichier de configuration doit être présent sur tous vos serveurs Exchange. En effet, si l'agent de scripting est activé et que l'un des serveurs ne possède pas le fichier alors des erreurs peuvent survenir lorsque l'on appelle une commande Powershell ou lorsqu’on lance la console Exchange (impossibilité de se connecter au serveur ne possédant pas le fichier de configuration).

L'agent de scripting ne possède aucune configuration par défaut. Il convient aux administrateurs Exchange de la créer. Celle-ci se fait au travers du fichier ScriptingAgentConfig.xml qui doit être positionné dans le dossier C:\Program Files\Microsoft\Exchange Server\V14\Bin\CmdletExtensionAgents (à moduler suivant le répertoire d'installation d'Exchange). Un exemple existe dans ce même répertoire nommé ScriptingAgentConfig.xml.sample).

Ce fichier contiendra tous nos scripts d'automatisation. Regardons maintenant la hiérarchie de ce fichier XML :

La balise Configuration contient l'ensemble des scripts qui seront utilisés par l'agent de scripting. C'est la balise racine.

Les balises Feature contiennent chaque fonctionnalité que l'on souhaite ajouter. Il peut y en envoir plusieurs au sein d'une balise Configuration. Elle possède chacune 2 attributs :

  • Name : pour le nom que l'on souhaite donner à notre fonctionnalité)
  • Cmdlets : permet de spécifier les Cmdlets Powershell Exchange qui vont déclencher la fonctionnalité. S'il y en a plusieurs, elles doivent être séparées par des virgules (Exemple : "New-Mailbox,Enable-Mailbox").

La balise API Call précice à quel moment la fonctionnalité se déclenche. Elle contient aussi le script qui sera lancé au déclenchement. Il peux y en envoir plusieurs au sein d'une balise Feature. Elle possède un attribut Name qui peut avoir 4 valeurs possibles :

  • OnComplete : Le script fourni sera exécuté lorsque la commande appelé aura déjà été exécuté. Exemple : Après la cr��ation d'une boîte aux lettres, on souhaite envoyer un mail de bienvenu à l'utilisateur et activer le Single Item Recovery.
  • Validate : Utile lorsque l'on souhaite valider des attributs. Le script se déclenchera avant l'exécution de la commande. Exemple : On souhaite être sur que les attributs Location et Phone ont été renseignés ou qu'ils respectent une certaine nomenclature pendant la création d'une boîte aux lettres. Ainsi l'administrateur recevra une erreur lors de l'exécution de la commande comme si ces attributs étaient obligatoire. Lorsque le retour est $null alors l'étape de validation est un succès.
  • ProvisionDefaultProperties : Cela permet de définir des valeurs par défaut pour les propriétés d'un objet. Exemple : Lorsque l'on crée une boîte aux lettres Exchange, on peux imaginer une règle qui choisit automatiquement la base de données en fonction de la première lettre du nom de la personne. Attention, dans cet exemple, il est nécessaire de désactiver l'agent Mailbox Resources Management ou de baisser sa priorité en dessous de celle de l'agent de scripting. En effet, l'agent Mailbox Resources Management est en charge de l'attribution automatique d'une base de données si aucune n'est renseignée.
  • UpdateAffectedIConfigurable : Cette API offre la possibilité de définir des propriétés juste avant l'opération de validation.

L'ordre d'exécution des différentes API lorsque l'on exécute une commande Exchange est le suivant  :

ProvisionDefaultProperties - UpdateAffectedIConfigurable - Validate – OnComplete

L'exécution de la commande Powershell Exchange a lieu entre les étapes Validate et OnComplete.

Enfin la balise Common permet de définir des fonctions Powershell pouvant être utilisées dans les scripts des balises ApiCall (A utiliser comme une librairie). On peut aussi charger ses propres scripts Powershell.

La mise en forme du fichier ScriptingAgentConfig.xml est importante. En effet, il apparait que lorsque des espaces inutiles sont présents, Exchange génère une erreur similaire à celle ci-dessous :

ScriptingAgent Error

De plus, un événement est généré :

ScriptingAgent Error Event 

Pour ma part, afin d'éviter tout problème, je me suis rendu compte qu’il ne fallait mieux pas commenter les scripts présents dans le fichier xml.

NB : Une fois l'agent de scripting activé, les modifications du fichier ScriptingAgentConfig.xml sont prises en compte automatiquement.

Exemple d'utilisation avec l'événement OnComplete :

Lorsqu'on utilise l'API OnComplete, la variable $succeeded existe si la commande a réussi. Cela permet de gérer les cas d'échecs (il serait impossible d'effectuer un traitement sur une boîte aux lettres qui n'existerait pas).

L’exemple ci-dessous est un fichier ScriptingAgentConfig.xml permettant d’activer la boîte d’archive et le single item recovery lorsqu’une nouvelle boîte aux lettres Exchange est créée (Commande New-Mailbox et Enable-Mailbox). On remarque que l’on accède aux paramètres définis par l’utilisateur via la variable $provisioningHandler qui contient un hastable nommé UserSpecifiedParameters.

Exemple d'utilisation avec l'événement Validate : 

Ce nouvel exemple montre cette fois-ci l'usage de l'API Validate. Ici, lorsqu'une boîte aux lettres de salle est créée, on vérifie que son nom est bien du type : Salle, XX où XX est un nombre. Si le test échoue alors une erreur est retourné avec un message qui sera affiché pour l’administrateur (que l’action soit réalisée via EMS ou l’EMC).

Ajouter un commentaire

Loading