On peut vous aider ?

Cherchez des réponses ou parcourez les rubriques de notre documentation

Voir aussi:

< All Topics
Print

Automatisation via l’API PowerShell

Introduction

L’automatisation via l’API ne propose aucune interface graphique.

Elle s’effectue avec l’assembly .NET Calame.Automation.dll.
Cet assembly est installée avec GTAnswer
Cet assembly est compilée pour le framework 3.5 et peut être appelée :

  • depuis le PowerShell (version 2)
  • depuis n’importe quel programme.NET
  • depuis Python

Tous les objets de l’assembly sont dans le namespace Calame.Automation.

Les commandes sont passées à GTServer via des classes nommées CmdXXXX. Il en existe deux types :

  • Les commandes d’exécution d’action qui héritent de la classe CmdExecuteAction
  • Les autres sont des classes statiques (ex. : CmdDoPolling)

Dans les deux cas, l’exécution se fait via la méthode Execute dont les paramètres et le type de retour diffèrent selon la commande. Cette méthode à toujours au moins un paramètre qui est les informations de connexion à l’instance.

L’utilisateur renseigné dans les informations de connexion décidera des droits possibles sur les objets GTServer dans le cadre de l’automatisation.
Il est souvent préférable de spécifier le login d’un administrateur ou d’un développeur pour la connexion.
Ainsi, il pourra exécuter toutes les actions, visualiser toutes les campagnes, etc…

Remarque :

Chacune des ces commandes encapsule en fait plusieurs commandes GTServer (notamment la connexion/déconnexion).

Informations de connexion

Les informations de connexion sont passées via un objet ConnectionInfo qui contient les champs suivants :

Connexion

  • Host (string) : nom du serveur de l’instance
  • Port (int) : le port de l’instance
  • SslProtocol (de type System.Security.Authentication.SslProtocols) : protocole SSL (défaut None)
  • CertificateServerName (string) : nom du certificat du serveur
  • Login (string) : nom de l’utilisateur se connectant à l’instance
  • Password (string) : mot de passe de l’utilisateur (<=3.9 si ce champ est vide, SHA1Password est utilisé)
  • SHA1Password (string) : SHA1 du mot de passe, utilisé si Password est vide (obsolète en 3.95 et+)

Comme précisé auparavant, il est souvent plus simple de se connecter pour l’automatisation avec un login Administrateur ou développeur pour ne pas avoir de restriction de droits.

Exemples :

  • PowerShell (avec SSL)
$connectioninfo = New-Object -typeName Calame.Automation.ConnectionInfo
$connectioninfo.Host = "monserveur"
$connectioninfo.Port = 6000
$connectioninfo.Login = "Admin"
$connectioninfo.Password = "MonMotDePasse"
$connectioninfo.SslProtocol = [System.Security.Authentication.SslProtocols]::Tls
$connectioninfo.CertificateServerName = "monserveur"
  • C# (sans SSL)
Calame.Automation.ConnectionInfo connectioninfo = new Calame.Automation.ConnectionInfo();
connectioninfo.Host = "monserveur";
connectioninfo.Port = 6000;
connectioninfo.Login = "Admin";
connectioninfo.Password = "MonMotDePasse";

Classes d’actions

Ces classes héritent de CmdExecuteAction et exécutent une action via l’une des deux méthodes suivantes:

Calame.Automation.ActionResult Execute(Calame.Automation.ConnectionInfo AInfo, bool AWaitTerminated, int AMaxWaitMin);

// surcharge pour laquelle AWaitTerminated = true et AMaxWaitMin = 60
Calame.Automation.ActionResult Execute(Calame.Automation.ConnectionInfo AInfo);

Paramètres :

  • AInfo (ConnectionInfo) : information de connexion
  • AWaitTerminated (bool) : booléen indiquant si on attend la fin de l’exécution de l’action
  • AMaxWaitMin (int) : nombre de minutes d’attente

Le type de retour est ActionResult :

Résultat de l'action

Les champs sont les suivants :

  • AcsId (long) : identifiant de l’exécution de l’action
  • ErrCode (int) : code d’erreur GTServer
  • ErrMsg (string) : message d’erreur
  • HasWarning (bool) : indique que l’exécution a produit des avertissements
  • Status (ActionStatus) : statut de l’exécution de type ActionStatus qui un enum prenant les valeurs suivantes :
NoneDans le cas ou on n’attend pas la fin de l’exécution (AWaitTerminated = false)
WaitTimeOutl’exécution ne s’est par terminée après AMaxWaitMin minutes
WaitErrorla demande de statut de l’exécution a généré une erreur (via une exception EActionException)
Pendingl’exécution est en attente de la fin d’une autre action
InProgressl’exécution est en cours
Terminatedl’exécution est terminée
Error l’exécution est terminée et il y a une erreur (via une exception EActionException)
Preparedl’action a été préparée (non disponible en automatisation)
Diagnostic l’action en mode diagnostique est terminée (non disponible en automatisation)

Lors d’une erreur d’exécution de l’action, une exception EActionException est levée. Ce type d’exception contient un champ ActionResult dont le champ Status vaut Error ou WaitError. Une exception ECommandException peut aussi se produire (par le login des infos de connexion n’est pas valide). Pour plus de détails voir le paragraphe sur la gestion des erreurs.

Si Status vaut WaitTimeOut, le statut d’exécution de l’action doit être vérifié à nouveau par la commande CmdGetActionStatus.

! Note : les actions SQL, d’integration, combinée, suppression de droit de réponse, creation d’utilisteurs n’utilisent pas le message

Exemples :

  • PowerShell :
function LanceMaCampagne
{
    $action = New-Object -typeName Calame.Automation.CmdActionCampaignLaunch
    $action.Name = "Le nom de mon action"
    $action.StatementDate = "2012-03-31"
    $action.UseCypher = $true
    $action.Message = [Calame.Automation.CmdGetMessageFromName]::Execute($connectioninfo, "Le nom du modèle de mon action", "Le nom du message");
    $action.Message.Subject = "Le nouveau sujet du message"
    try
    {
        $result = $action.Execute($connectioninfo, $true, 10)
        if ($result.Status -eq [Calame.Automation.ActionStatus]::WaitTimeOut)
        {   
            echo "Timeout : $result"
        }
        return $result
    }
    catch [Calame.Automation.EActionException]
    {
        $e = $_.Exception;
        Write-Host $e.Message.ToString() -foregroundcolor red -backgroundcolor yellow
        return $e.ActionResult  
    }
    catch [Calame.Automation.ECommandException] 
    {
        $e = $_.Exception;
        Write-Host $e.Message.ToString() -foregroundcolor red -backgroundcolor yellow
        return $e.ErrCode
    }   
}

Action de lancement de collecte : CmdActionCampaignLaunch

Champs :

  • Name (string): nom de l’action
  • Message (Calame.Automation.Message) : message, si null utilisation du premier message trouvé.
  • StatementDate (DateTime): date d’arrêté, ce champ n’est utilisé que si l’action n’a pas de source de date d’arrêté
  • GlobalRedirectAddress (string): adresse de redirection globale
  • UseCypher (bool): chiffrement de la réponse (si l’instance à un certificat), faux par défaut

Action d’intégration : CmdActionCampaignIntegration

Champs :

  • Name (string): nom de l’action
  • StatementDate (DateTime): date d’arrêté, ce champ n’est utilisé que si l’action n’a pas de source de date d’arrêté

Action de lancement de restitution : CmdActionReportingQst

! Note : GT >= GT 3.7

Champs :

  • Name (string): nom de l’action
  • Message (Calame.Automation.Message) : message, si null utilisation du premier message trouvé.
  • StatementDate (DateTime) : date d’arrêté, ce champ n’est utilisé que si l’action n’a pas de source de date d’arrêté.
  • GlobalRedirectAddress (string): adresse de redirection globale
  • UseCypher (bool): chiffrement de la réponse (si l’instance à un certificat), faux par défaut

Action de script SQL : CmdActionSQL

Champs :

  • Name (string): nom de l’action

Action de fermeture de campagne : CmdActionCampaignClose

Champs :

  • Name (string): nom de l’action, non utilisé: il faut utiliser le nom du modèle
  • Message (Calame.Automation.Message) : message, si null utilisation du premier message trouvé.
  • StatementDate (DateTime): date d’arrêté
  • ModelName (string): nom du modèle
  • UseDefaultActionSettings (bool): utiliser les paramètres par défaut de l’action
  • DoSendMessage (bool): envoyer le message de fermeture (ignoré si UseDefaultActionSettings = true)
  • AttachQst (bool): joindre la dernière réponse ou le qst envoyé (ignoré si UseDefaultActionSettings = true)
  • AttachPDF (bool): joindre la dernière réponse en PDF (ignoré si UseDefaultActionSettings = true)
  • AttachHisto (bool): joindre l’historique (ignoré si UseDefaultActionSettings = true)

Action de relance : CmdActionCampaignFollowup

Champs :

  • Name (string): nom de l’action, non utilisé: il faut utiliser le nom du modèle
  • Message (Calame.Automation.Message) : message, si null utilisation du premier message trouvé.
  • StatementDate (DateTime): date d’arrêté
  • ModelName (string): nom du modèle
  • UseDefaultActionSettings (bool): utiliser les paramètres par défaut de l’action
  • AttachQst (bool): joindre la dernière réponse ou le qst envoyé (ignoré si UseDefaultActionSettings = true)
  • AttachPDF (bool): joindre la dernière réponse en PDF (ignoré si UseDefaultActionSettings = true)
  • AttachHisto (bool): joindre l’historique (ignoré si UseDefaultActionSettings = true)
  • SelectNoAnswers (bool): relancer les entités sans réponse
  • SelectPending (bool): relancer les entités en attente de validation
  • SelectInvalidated (bool): relancer les entités invalidées.
  • SelectEntities (List of AnswerEntity) – pour sélectionner les entités à relance (version >= 2019)

Exemples :

  • PowerShell :

Relance en sélectionnant les entités (donc version >= 2019)

function RelanceParEnt
{
  $private:datearrete = [DateTime]::Parse("26/09/2018")
  $private:modelname = "Test"
  $private:entities = [Calame.Automation.CmdListAnswer]::Execute($conn, $modelname, $datearrete)
  $private:selected = New-Object 'System.Collections.Generic.List[Calame.Automation.AnswerEntity]'

  foreach ($private:ent in $entities)
  {
    if (($ent["Pays"] -eq "CH") -or ($ent["Pays"] -eq "IT"))
    {
      $selected.Add($ent)
    }
  }

  $private:cmd = New-Object -typeName Calame.Automation.CmdActionCampaignFollowup
  $cmd.ModelName = $modelname
  $cmd.StatementDate = $datearrete
  $cmd.UseDefaultActionSettings = $false
  $cmd.AttachQst = $true
  $cmd.SelectedEntities = $selected
  return $cmd.Execute($conn, $true, 15)
}

Action combinée : CmdActionCombined

! Note : GT >= GT 4.0.0

Champs :

  • StatementDate (DateTime): date d’arrêté, ce champ n’est utilisé que si l’action n’a pas de source de date d’arrêté

Action de création d’utilisateur : CmdActionCreateMassUser

! Note : GT >= GT 4.0.0

Action de suppression de droit de réponse : CmdActionRemoveAnswerRights

! Note : GT >= GT 4.0.0

Messages

Les classes d’action possèdent un champ message de type Calame.Automation.Message. Il y a deux manières de créer un message :

  • Directement en appelant le constructeur et en remplissant les champs
  • Via la classe de commande CmdGetMessageFromName qui renvoie un message depuis le nom du modèle et le nom du message (cf. l’exemple ci-dessus).

Une fois que l’on a un objet message, on peut modifier ses champs (sujet,…)

Messages

Remarque :

  • Le champ message pour les actions SQL et d’intégration est ignoré
  • Un message créé directement par le constructeur n’a pas de type. Au contraire, le message renvoyé par CmdGetMessageFromName est typé. Si ce message est passé à une action dont le type ne correspond pas (par exemple une action de lancement avec un message de restitution), une exception générique est soulevée à l’exécution de l’action. Le type de message une propriété interne inaccessible.
  • à partir de GT 3.7 : La valeur d’enum MessageAutoTo.OverrideTo n’est disponible que pour les messages de relance. Elle permet de surcharger le champ « To » via la propriété OverrideTo

Classes statiques

Gestion des messages : CmdGetMessageFromName

Renvoie le message depuis le nom du modèle et le nom du message :

Calame.Automation.Message Execute(Calame.Automation.ConnectionInfo AInfo, string AModelName, string AMessageName)

Paramètres :

  • AInfo (ConnectionInfo) : information de connexion
  • AModelName ( string) : nom du modèle
  • AMessageName ( string) : nom du message

Gestion du polling : CmdDoPolling, CmdIsPolling et CmdGetPollingLog

Demande de polling

Demande de polling via la classe CmdDoPolling :

bool Execute(Calame.Automation.ConnectionInfo AInfo, bool AWaitTerminated, int AMaxWaitMin)

Paramètres :

  • param AInfo : information de connexion
  • type AInfo : ConnectionInfo
  • param AWaitTerminated : booléen indiquant si on attend la fin du polling
  • type AWaitTerminated : bool
  • param AMaxWaitMin : nombre de minutes d’attente (si AWaitTerminated est à true)
  • type AMaxWaitMin : int
  • rtype : bool

Exemples :

  • PowerShell :
$res = [Calame.Automation.CmdDoPolling]::Execute($connectioninfo, $true, 30)
  • C# :
bool res = Calame.Automation.CmdDoPolling.Execute(connectioninfo, true, 30);

Demande de polling avancée

Demande de polling avec les résultats via la classe CmdDoPolling :

Calame.Automation.PollingResult ExecuteEx(Calame.Automation.ConnectionInfo AInfo, bool AWaitTerminated, int AMaxWaitMin)

Les paramètres sont les mêmes que pour la méthode précédente :

  • AInfo (ConnectionInfo) : information de connexion
  • AWaitTerminated (bool) : booléen indiquant si on attend la fin du polling
  • AMaxWaitMin (int) : nombre de minutes d’attente (si AWaitTerminated est à true)

Le résultat est un objet de type PollingResult :

Objet PollingResult

Polling en cours

Pour savoir si un polling est en cours on utilise la classe CmdIsPolling :

bool Execute(Calame.Automation.ConnectionInfo AInfo)

Log de polling

La commande CmdGetPollingLog renvoie le log d’un polling :

string Execute(Calame.Automation.ConnectionInfo AInfo, long APollId)

Paramètres :

  • AInfo (ConnectionInfo) : information de connexion
  • APollId (long) : valeur du champ PollId de l’objet renvoyé par CmdDoPolling.ExecuteEx
  • rtype : string

Exemple PowerShell :

$res = [Calame.Automation.CmdDoPolling]::ExecuteEx($connectioninfo, $true, 30)
$log = [Calame.Automation.CmdGetPollingLog]::Execute($connectioninfo, $res.PollId)

Gestion des actions : CmdGetActionStatus et CmdGetActionLog

La classe CmdGetActionStatus renvoie, le même ActionResult que l’exécution d’une action via le champ AcsId :

Calame.Automation.ActionResult Execute(Calame.Automation.ConnectionInfo AInfo, long AAcsId)

Paramètres :

  • AInfo (ConnectionInfo) : information de connexion
  • AAcsId : identifiant de l’exécution de l’action

La classe CmdGetActionLog renvoie la portion des logs de l’instance correspondant à l’exécution de l’action.

string Execute(Calame.Automation.ConnectionInfo AInfo, long AAcsId)

Les paramètres sont les même que pour CmdGetActionStatus. Le log renvoyé est sous forme d’une chaine qui contient XML.

Important : si l’action a généré une erreur, le log renvoyé ne la contient pas (mais elle est bien présente dans les logs fichiers de l’instance). Elle est accessible via l’ActionResult de la commande d’exécution ou de CmdGetActionStatus.

Gestion des campagnes : CmdDeleteCampaign et CmdListCampaign

CmdDeleteCampaign : Suppression de campagne

La classe CmdDeleteCampaign est utilisée pour supprimer une campagne fermée :

void Execute(Calame.Automation.ConnectionInfo AInfo, string AModelName, DateTime AStatementDate, bool ADeleteHisto)

Paramètres :

  • AInfo (ConnectionInfo) : information de connexion
  • AModelName : nom du modèle de la campagne
  • AStatementDate: date d’arrêté de la campagne
  • ADeleteHisto : true pour supprimer l’historique de cette campagne

La fonction ne renvoie rien. Si une erreur ce produit, ce sera via une exception ECommandException.

Exemple :

  • PowerShell :
[CmdDeleteCampaign]::Execute($connectioninfo, "MonModèle", [DateTime]::Parse( "2014-02-29"), $true)
CmdListCampaign : liste des campagnes

La classe CmdListCampaign renvoie la liste des campagnes :

List Execute(Calame.Automation.ConnectionInfo AInfo)

La classe Campaign est définie comme suit :

Classe Campaign

Exemple :

  • PowerShell

Cette fonction affiche la liste des campagnes fermées. Remarquez la syntaxe avec + pour accéder à un type imbriqué.

function ListeCampagnesClosed
{
    $list = [Calame.Automation.CmdListCampaign]::Execute($connectioninfo)
    foreach ($camp in $list)
    {
        if ($camp.Status -eq [Calame.Automation.Campaign+CampStatus]::Closed)
        {
            echo $camp
        }
    }
}

Gestion des réponses et des questionnaires

Date de dernière réponse : CmdLastAnswerDateForCampaign

! Note: GT >= 3.1 build 1862

La commande CmdLastAnswerDateForCampaign renvoie la date d’envoi par le correspondant de la dernière réponse reçue par GTServer.

Cette commande doit être exécutée dans le cas où l’on souhaite surveiller les arrivées de nouvelles réponses et déclencher certaines actions (intégration, restitution, …) en fonction de ces nouvelles réponses.
Le déclenchement de ces actions annexes devra être soumis à l’arrivée effective d’une nouvelle réponse afin de ne pas exécuter trop fréquemment ces actions.

DateTime Execute(Calame.Automation.ConnectionInfo AInfo, string AModelName, DateTime AStatementDate)

Paramètres :

  • AInfo (ConnectionInfo) : information de connexion
  • AModelName (string) : nom du modèle de la campagne
  • AStatementDate (DateTime) : date d’arrêté de la campagne

Exemple (PowerShell) :

[CmdLastAnswerDateForCampaign]::Execute($connectioninfo, "Modèle", [DateTime]::Parse("2014-02-29"))
Liste des réponses : CmdListAnswer

! Note: GT >= 3.9

La commande CmdListAnswer renvoie la liste des réponses (par entité) d’une campagne.

AnswerEntities Execute(Calame.Automation.ConnectionInfo AInfo, string AModelName, DateTime AStatementDate)

Paramètres :

  • AInfo (ConnectionInfo) : information de connexion
  • AModelName (string) : nom du modèle de la campagne
  • AStatementDate (DateTime) : date d’arrêté de la campagne

L’objet renvoyé de type AnswerEntities décrit les réponses de la campagne par entités :

AnswerEntities

Exemple C#

// Récupération de la liste
AnswerEntities entities = CmdListAnswer.Execute(info, "Test", DateTime.Parse("07/02/2012"));

// Affichage des axes de diffusion + axes de validation supplémentaires + axe visualisations
// Ici on a deux axes de diffusion: Pays et Ville
foreach (AnswerEntities.Axis axis in entities.ValidationAxes)
{
Console.WriteLine("Axe: {0}, Usage: {1}, Type .NET: {2}", axis.Name, axis.Usage, axis.DataType);
}

// pour chaque entité
foreach (AnswerEntity ent in entities)
{
        Console.WriteLine("===========================");
        // Affiche l'entité, ici on a deux axes de diffusion: Pays et Ville
        Console.WriteLine("Pays: {0}  Ville: {1}", ent["Pays"], ent["Ville"]);

        // Nombre de réponses
        Console.WriteLine("Nombre de réponses: {0}", ent.Answers.Count);

        // Tri des réponses par date d'envoi croissante
        ent.Answers.Sort(
        delegate (Answer left, Answer right)
        {
        return DateTime.Compare(left.DateAnswerSent, right.DateAnswerSent);
        });

        // Pour chaque réponse, affichage du statut dans l'ordre d'envoi
        // Et l’axe de visualisation Région
        for (int i = 0; i < ent.Answers.Count; i++)
        {
        Answer a = ent.Answers[i];
        Console.WriteLine("Réponse n°{0} d'Id {1} envoyée le {2}, statut: {3}", 
        i + 1, a.AnwserId, a.DateAnswerSent, a.ValidationStatus);
		object visu = a.GetVisualizationAxisValue("Région");
        if (visu != null)
			Console.WriteLine("Axe de visualisation Région {0}", visu);

        }

        // Dernière réponse ou validé
        Answer ans = ent.GetLastOrValidated();

        if (ans != null)
        {
        Console.WriteLine("L'Id de la dernière réponse est {0}", ans.AnwserId);
        }
        else
        {
        Console.WriteLine("Pas de réponse");
        }
}
Obtenir le questionnaire d’une réponse : CmdGetAnswer

! Note : GT >= 3.5

Permet de récupérer une réponse.

La commande CmdGetAnswer écrit sur disque le questionnaire (fichier .qst) d’une réponse.

bool Execute(Calame.Automation.ConnectionInfo AInfo, string ADestinationFileName, long AAnswerId, bool AForAnswer=false)

Paramètres :

  • AInfo (ConnectionInfo) : information de connexion
  • ADestinationFileName (string) : nom du fichier de destination pour enregistrer la réponse
  • AAnswerId (long) : Id de la réponse (champ AnswerId pour un objet de la classe Answer obtenue à partir de CmdListAnswer.Execute)
  • AForAnswer (bool) : si ce paramètre est vrai, le fichier qst correspondant à la réponse envoyée est fonctionnel : on peut transmettre une nouvelle réponse en ouvrant ce questionnaire dans Answer. Sinon, l’envoi de la réponse est bloqué. Ce paramètre dépend du droit « Ouvrir une réponse avec Answer ».
Obtenir un questionnaire envoyé : CmdGetQstSent

! Note : GT >= 3.7

Permet de récupérer un questionnaire envoyé.

La commande CmdGetQstSent écrit sur disque un questionnaire envoyé (fichier .qst).

bool Execute(Calame.Automation.ConnectionInfo AInfo, string ADestinationFileName, long AQstSentId, bool AForAnswer=false)

Paramètres :

  • AInfo (ConnectionInfo) : information de connexion
  • ADestinationFileName (string) : nom du fichier de destination pour enregistrer la réponse
  • AQstSentId (long) : Id du qst envoyé (champ QstSentId pour un objet de la classe Answer ou de la classe QstSent obtenue(s) à partir de CmdListAnswer.Execute)
  • AForAnswer (bool) : si ce paramètre est vrai, le fichier qst correspondant au questionnaire envoyé est fonctionnel : on peut transmettre une réponse en ouvrant ce questionnaire dans Answer. Sinon, l’envoi de la réponse est bloqué. Ce paramètre dépend du droit « Ouvrir un questionnaire envoyé avec Answer ».
Fermeture d’un questionnaire : CmdCloseQst

Permet de fermer un questionnaire envoyé en refusant les réponses passées et futures ou seulement les réponses futures.

void Execute(ConnectionInfo AInfo, long AQstId, bool APastAndFuture)

Paramètres :

  • AInfo (ConnectionInfo) : information de connexion
  • AQstId ( long) : Id du qst (champ QstSentId pour un objet de la classe Answer ou de la classe QstSent).
  • APastAndFuture (bool): Booléen indiquant si les réponses passées sont également supprimées
Suppression d’une réponse : CmdDeleteAnwser

Permet de supprimer une réponse spécifique selon son identifiant (obtenue par le champs AnswerId de la classe Answer).

La suppression des réponses est irrémédiable.

void Execute(ConnectionInfo AInfo, long AAnswerId)

Paramètres

  • AInfo (ConnectionInfo) : information de connexion
  • AAnswerId ( long) : Id de la réponse (champ AnswerId pour un objet de la classe Answer).

Gestion des modèles

! Note : GT >= GT 4.0.0

Tous les paramètres sont passés par la classe GtModel (y compris les droits) :

  • Id (long) – Id du modèle
  • Name (string) – nom du modèle
  • Description (string) – description du modèle
  • Type (ModelType) – type du modèle
Lister les modèles : CmdListModel

La commande CmdListModel permet de lister les modèles :

list Execute(Calame.Automation.ConnectionInfo AInfo)

Paramètres

  • AInfo (ConnectionInfo) – informations de connexion

Renvoie

  • liste des utilisateurs
  • Type renvoyé : List of GtModel

Gestion des projets

! Note : GT >= GT 4.0.0

Tous les paramètres sont passés par la classe GtProject (y compris les droits) :

  • Id (long) – Id du projet
  • Name (string) – nom du projet
  • Description (string) – description du projet
  • PublicationsCount (int) – nombre de publications du projet
  • ModelCount (int) – nombre de modèles du projet
  • ActionCount (int) – nombre d’actions du projet
Lister les projets : CmdListProject

La commande CmdListProject permet de lister les modèles :

list Execute(Calame.Automation.ConnectionInfo AInfo)

Paramètres

  • AInfo (ConnectionInfo) – informations de connexion

Renvoie

  • liste des utilisateurs
  • Type renvoyé : List of GtProject

Gestion des utilisateurs

Création de nouveaux utilisateurs et affectation des droits pour ces nouveaux utilisateurs

La commande CmdInsertUser permet d’insérer un nouvel utilisateur :

void Execute(Calame.Automation.ConnectionInfo AInfo, Calame.Automation.NewUser AUser)

Tous les paramètres sont passés par la classe NewUser (y compris les droits) :

Classe NewUser

Exemple C#

// création de l’objet
NewUser user = new NewUser();

// Login/Mot de passe
user.Login = "Nouvel_Utilisateur";
user.Password = "motdepasse";

// Privilège
user.Privilege = NewUser.UserPrivilege.None;

// droits sur les modèles via une liste de couple (Modèle, Groupe)
// NB : ici, l’utilisateur fait partie de deux groupes pour « Modele2 »
user.Rights = new List();
user.Rights.Add(new NewUser.ModelGroupCouple("Modele1", "Gestionnaire"));
user.Rights.Add(new NewUser.ModelGroupCouple("Modele2", "Visualiseur"));
user.Rights.Add(new NewUser.ModelGroupCouple("Modele2", "Valideur"));

// appel de la commande
CmdInsertUser.Execute(info, user);
Vérification du mot de passe : CmdCheckPassword

La commande CmdCheckPassword permet de vérifier la validité d’un mot de passe par rapport aux contraintes configurées au niveau de l’instance (cf GtAdmin).

void Execute(ConnectionInfo AInfo, string APwd)

Paramètres :

  • AInfo : information de connexion
  • APwd : Mot de passe dont la validité est à vérifier
Modification des utilisateurs

La commande CmdEditUser permet de modifier les informations d’un utilisateur.

void Execute(ConnectionInfo AInfo, User AUser)

L’objet User passé en paramètre doit contenir un Id valide, cet Id peut être obtenu grâce à la commande CmdListUser.

Suppression des utilisateurs

La commande CmdDeleteUser permet de supprimer un utilisateur de la base.

void Execute(ConnectionInfo AInfo, int AUserId)

L’Id de l’utilisateur peut être obtenu grâce à la commande CmdListUser.

Liste des utilisateurs

La commande CmdListUser retourne la liste des utilisateurs de l’instance.

List Execute(ConnectionInfo AInfo)

Gestion des erreurs

La gestion des erreurs se fait via des exceptions qui héritent de EAutomationException :

Classe EAutomationException

Le code d’erreur (champ ErrCode) de l’exception est le code d’erreur GTServer (le même que celui affiché par GTAnswer). ErrMsg contient le message d’erreur. Les exceptions ECommandException sont soulevées pour les commandes statiques.

Une exception EActionException est soulevée lors de l’exécution d’une action si toutefois cette action a pu démarrer. Dans le cas contraire, une exécution d’action peut soulever une exception ECommandException car elle encapsule entre autre la commande de logon à GTServer.

D’autres exceptions du .NET framework peuvent aussi être soulevées notamment System.Net.Sockets.SocketException pour les erreurs de communication avec le serveur (par exemple, s’il n’est pas démarré).

Le code C# suivant est un template d’exécution d’une action passée en paramètre (pour rappel les classes d’action héritent de CmdExecuteAction) :

// renvoie true si aucune erreur, sinon ErrMsg contient le message d’erreur
bool ExecuteAction(ConnectionInfo AInfo, CmdExecuteAction AAction, out string ErrMsg)
{
    ErrMsg = "";
    try
    {
        ActionResult resAction = AAction.Execute(AInfo, true, 60);
        // faire ce qu’on veut de resAction
        return true;
    }
    catch (ECommandException ECmd)
    {
        ErrMsg =  String.Format("Erreur à l'exécution d’une commande:\nCode: {0}\nMessage: {1}", 
        ECmd.ErrCode, 
        ECmd.Message);
        return false;
    }
    catch (EActionException EAct)
    {
        ErrMsg = String.Format("Erreur à l'exécution de l'action {0}:\nCode: {1}\nMessage: {2}",
            AAction.Name,
            EAct.ErrCode,
            EAct.Message);
            return false;
    }
    catch (System.Net.Sockets.SocketException ES)
    {
        ErrMsg =  String.Format("Erreur de communication avec le serveur:\nType: {0}\nMessage: {1}",
        ES.GetType(),
        ES.Message);
        return false;
    }
    catch (Exception E)
    {
        ErrMsg =  String.Format("Autre erreur:\nType: {0}\nMessage: {1}",
        E.GetType(),
        E.Message);
        return false;
    }
}

NB : un script Powershell doit inclure la commande suivante pour que les erreurs puissent être interceptées lors de l’exécution du script

$ErrorActionPreference = "Stop"

Cette commande peut également être présente dans le script de profil de l’utilisateur.

Cette commande devra être ajoutée au tout début du script.

Sécurisation des informations de connexion

L’utilisation d’un script Powershell laissera apparaître en clair les informations de connexion à GTServer ou à la base de données (si le script doit se connecter à la base de données).

Le script devrait être exécuté a priori sur une machine à accès restreint.
Si le fait que les informations de connexion (à GTServer ou à la base de données) n’est pas acceptable pour la politique de sécurité de l’infrastructure, il est alors préférable d’utiliser par exemple une assembly .NET qui ira lire ou écrire les informations de connexion/configuration dans un fichier texte sous une forme encryptée.

Demandes multiples d’exécutions d’actions ou de polling

GTServer n’exécute jamais simultanément un polling et/ou une action quelconque (lancement de qst ou restitution ou restitution à base de qst, intégration de campagne, action SQL).

Si un polling est demandé alors qu’une action ou un autre polling est en cours d’exécution, la demande de polling sera rejetée.

A chaque nouvelle demande d’exécution d’action et ce quelle que soit la source de la demande (automatisation ou n’importe quel utilisateur), un thread est créé sur le serveur attendant qu’un mutex spécifique soit disponible sur le serveur.
Lorsque l’action en cours de traitement se termine, le sémaphore est libéré et le système Windows sur le serveur lance l’un des thread actuellement en attente du mutex.

Il est donc conseillé dans le cadre de l’automatisation :

  • de toujours attendre la fin de l’exécution de l »action qui a été demandée par le script ou l’assembly. Si l’ActionResult a le Status WaitTimeOut, le statut d’exécution pourra à nouveau être interrogé via CmdGetActionStatus après un temps d’attente.
  • de réitérer la demande de polling quelque temps après si celle-ci a été rejetée.
  • d’exécuter les scripts d’automatisation en-dehors des plages habituelles d’utilisation par les gestionnaires/valideurs, pour éviter l’afflux de demandes au serveur.
  • de nettoyer régulièrement la boîte mail associée à GTServer pour éviter un temps de polling trop long (en préservant les mails de réponse d’Answer), de vérifier les temps de connexion en réception de GTServer au serveur de messagerie, voire de passer en réponse http (et supprimer la configuration de polling de messagerie) pour diminuer les temps de polling.

Enfin, il est très vivement recommandé lorsque des actions d’intégration sont exécutées à intervalles rapprochés (moins de deux heures), de prendre la précaution de n’exécuter l’action d’intégration que lorsque de nouvelles réponses sont effectivement parvenues à GTServer.
Plus généralement, il est fortement recommandé de n’exécuter les actions (lancement de campagne, intégration, envoi de restitution) que lorsque cela est nécessaire : nouvelles réponses, nouvelles données en base, changement de statut, etc… Si ces conditions ne sont pas respectées, un fonctionnement optimal de GTServer ne pourra pas être garanti.

Les opérations à mettre en oeuvre sont alors généralement les suivantes :

  • Demande d’exécution d’un polling
  • Extraction de la date de dernière réponse pour la campagne
  • Comparaison de cette date avec la date de dernière réponse intégrée en base. Cette dernière opération demande un accès direct (via ODBC/OleDb) ou indirect (via production et lecture de fichier) à la base Client.
  • Exécution de l’action d’intégration si une nouvelle réponse est arrivée
  • Exécution d’une ou plusieurs opérations complémentaires au besoin

Chargement de l’assembly d’automatisation avec un script Powershell

Le chargement de l’assembly Calame d’automatisation se fait simplement au travers de la méthode statique Reflection.Assembly.LoadFrom ou de l’une de ses dérivés.

[void] [system.reflection.assembly]::loadfrom("C:\Program Files (x86)\Calame\bin\Calame.Automation.dll")

Cette commande devra être ajoutée au tout début du script.

Autorisation d’exécution des scripts Powershell

Par défaut l’exécution des scripts Powershell n’est pas autorisée.

Vous pouvez vérifier ce point en utilisant via la console la commande suivante à partir de l’invite en ligne de commandes.

powershell Get-ExecutionPolicy

Vous pouvez autoriser l’exécution de tous les scripts Powershell en utilisant la commande suivante à partir de l’invite en ligne de commandes lancée en tant qu’administrateur. Il est cependant préférable d’affiner l’autorisation d’exécution à certains scripts seulement.

powershell Set-ExecutionPolicy Unrestricted

Vous pouvez également autoriser ponctuellement l’exécution d’un script powershell via la ligne de commande suivante
powershell -ExecutionPolicy Bypass -File

Les arguments suivants de la ligne de commande d’exécution powershell peuvent être intéressants
-NoLogo -NonInteractive

Consultez l’aide de Microsoft sur Powershell pour plus d’informations

Was this article helpful?
0 out Of 5 Stars
5 Stars 0%
4 Stars 0%
3 Stars 0%
2 Stars 0%
1 Stars 0%
5
How can we improve this article?
How Can We Improve This Article?
Table of Contents