Le composant IP de 4D Business Kit Résumé 4D Notes techniques

Le composant IP de 4D Business Kit
Par
Sebastian FREY
Martine Mourier, Consultante 4D (developer network)
Note technique 4D-200204-11-FR
Version 1
Date 1 Avril 2002
Résumé
Voici un exemple d'utilisation du composant IP 4D Business Kit. La base exemple dialogue avec un serveur
4DBK, échange des données et éxecute en local des traitements pour le serveur.
4D Notes techniques
Copyright © 1985-2003 4D SA - Tous droits réservés
Tous les efforts ont été faits pour que le contenu de cette note technique présente le maximum de fiabilité possible.
Néanmoins, les différents éléments composant cette note technique, et le cas échéant, le code, sont fournis sans garantie d'aucune sorte.
L'auteur et 4D S.A. déclinent donc toute responsabilité quant à l'utilisation qui pourrait être faite de ces éléments, tant à l'égard de leurs
utilisateurs que des tiers.
Les informations contenues dans ce document peuvent faire l'objet de modifications sans préavis et ne sauraient en aucune manière
engager 4D SA. La fourniture d u logiciel décrit dans ce document est régie par u n octroi de licence dont les termes sont précisés par
ailleurs dans la licence électronique figurant sur le support d u Logiciel et de la Documentation afférente. Le logiciel et sa documentation
ne peuvent être utilisés, copiés o u reproduits sur quelque support que ce soit et de quelque manière que ce soit, que conformément aux
termes de cette licence.
Aucune partie de ce document ne peut être reproduite o u recopiée de quelque manière que ce soit, électronique o u mécanique, y compris
par photocopie, enregistrement, archivage o u tout autre procédé de stockage, de traitement et de récupération d'informations, pour
d'autres buts que l'usage personnel de l'acheteur, et ce exclusivement aux conditions contractuelles, sans la permission explicite de 4D
Le composant IP 4D Business Kit
4D Business Kit est une application d’e-commerce double-cliquable, "packagée" dont le code source n’est
pas accessible. On pourrait donc croire que 4D Business Kit est un produit fermé, rien n’est plus faux. Et
ceci grâce au composant IP 4D Business Kit.
Le Composant IP est une collection de méthodes 4D. Comme tout composant, il peut être installé avec 4D
Insider dans n’importe quelle application 4D 6.7 minimum.
Le Composant IP prend peu de place : il contient seulement une dizaine de méthodes. Il ne nécessite aucun
ajout de tables ou de formulaires dans votre base 4D. En revanche vous devez avoir installé 2 plug-ins : les
4D Internet Commands et un plug-in spécifique 4D Business Kit. Ce plug-in permet surtout une grande
efficacité dans le parsing de textes dans les BLObs.
Le Composant IP peut être très facilement retiré de votre base à tout moment grâce à 4D Insider.
Ce composant est très puissant. Ceci est lié à son haut degré d’intégration des marqueurs dans le langage 4D
Business Kit. Le Composant IP peut être utilisé pour EXECUTER presque tous les marqueurs 4D BK sur le
serveur BK. Cela signifie que tout ce qu’il est possible de faire avec 4D BK au Niveau des documents HTML
est possible avec le Composant IP. Si vous êtes familier avec le langage des marqueurs de 4D BK, vous
apprécierez le Composant IP et inversement.
Cette note technique est accompagnée d’une petite base de démonstration, appelée "The demo
application". Cette application "diaogue" avec une instance de 4D BK et échange des données avec elle. Pour
utiliser cette note technique, vous devez avoir téléchargé cette base exemple et avoir une version minimum 1.0
de 4D Business Kit.
Mise en place de 4D BK et de la base de démonstration
Tout d’abord, lancez la base de démonstration. Vous arrivez en mode Menus Créés. Allez dans le menu
"File" et choisissez "Préférences". Par défaut la base démo ira chercher un 4D BK lancé sur la même
machine (à l’adresse 127.0.0.1), sur le port 80, le port standard. Si vous souhaitez faire tourner 4D BK sur
une autre machine, changez les préférences. Notez que l’application attend un code de 4 caractères pour la
boutique 4D BK. Dans l’exemple, ce code est "DEMO". Vous pouvez bien sûr le changer, mais tout au long
de cette note, nous utiliserons ce code.
La première information à saisir est le code boutique. Tapez DEMO puis le libellé obligatoire. Onglet "Web"
saisissez votre serveur SMTP (par exemple mail.votrecompagnie.com).
Onglet "Web#2", augmentez la valeur de clôture automatique de session (par défaut : 10 minutes).
Quelques pages HTML sont à utiliser pour cet exemple : remplacez le dossier DEMO_Site créé avec votre
boutique par le dossier de la note technique. Si vous utilisez un 4D Business Kit français, mettez à jour les
pages françaises.
Utilisation du Composant IP
Le composant assure les trois fonctions principales suivantes :
Faire exécuter des instructions 4DBK par le serveur 4D Business Kit
Mettre à jour ou synchroniser les articles d’un serveur 4D Business Kit
Déléguer en local, l’exécution de certaines taches internes du serveur 4DBK
I Faire exécuter des instructions 4DBK par le serveur 4D Business Kit
Vous pouvez travailler soit avec une session existante de BK en utilisant son ID ou en créer une nouvelle. Il y
a deux commandes spécifiques pour cela :
$tSessionID :=4DBK_SessionNew("bktest.4d.com";80)
permet de créer un nouveau canal de communication
$tSessionID := 4DBK_SessionOpen($tSessionID ; "testbk.4d.com";80)
Utilise un canal préalablement créé.
Le "cœur" du Composant IP est la commande 4DBK_Execute. Cette méthode est utilisée pour faire exécuter
du code 4DBK au serveur 4D Business Kit et récupérer un résultat. Quelquefois, il n’y a pas de résultat ;
d’autres fois vous demanderez à 4D Bussiness Kit de renvoyer une "page" de données, et cette page peut
être de taille importante.
L’utilisation de la méthode 4DBK_Execute est très simple :
C _ B L O B ($xBlob)
APP_BKExecute diffère de 4DBK_Execute car elle possède un troisième paramètre optionnel. Ce
paramètre est un pointeur soit sur une variable texte ou blob ou sur un champ. Cette variable contiendra le
résultat de la commande 4DBK_Execute, s’il y en a un. APP_BKExecute retourne un Entier long dans $0
au lieu du blob retourné par la méthode classique.
Un autre exemple démontrant l’intérêt des sous-méthodes : chaque chaîne de commande exécutée avec
4DBK_Execute doit avoir comme premières commandes "4DBKStoreSet/xxxx" où xxxx est le code de 4
lettres de la boutique. APP_BKExecute vérifie que cette chaîne existe dans chaque commande et sinon la
rajoute.
Souvent lorsque vous voulez exécuter une chaîne de commande sur le serveur Business Kit vous ne souhaitez
pas récupérer un résultat mais voulez juste savoir si la commande s’est correctement déroulée ou non. Par
exemple si vous essayez d’ajouter un élément dans un caddie, vous aurez le code suivant :
$tCommand := "" $tCommand := $tCommand + "4DBKStoreSet/ "+<>APP_t_StoreCode+ ";"
$tCommand := $tCommand + "4DBKQuantitySet/ +"+String($iQuantity)+ ";"
$tCommand := $tCommand + "4DBKBasketSet/"+$ItemCode
Vous ne récupérez aucune donnée : vous voulez simplement savoir si l’article a bien été rajouté.
En utilisant 4DBK_Execute voici ce que vous devez faire :
C _ B L O B($xBlob)
$xBlob :=4DBK_Execute ($tSessionID;$tCommand)
C _ T E X T E($tResult)
$tResult:=BLOB vers texte ($xBlob ; Texte sans longueur)
S i ($tResult = "[Err@") `une erreur est survenue
S i n o n `tout est OK
Fin de si
Si vous souhaitez vraiment savoir si votre article a bien été rajouté, voici une autre façon avec la sousméthode APP_BKExecute :
$fOK :=(APP_BKExecute ($tSession ; $tCommand) =0)
$tFrom := <>APP_t_EmailAdress `définie dans les Préférences
$tTo := [Customer]Email
$tSubject := "4DBK Tech Note"
$tPageName := "Mail_example.htm"
$iResult := APP_BkMailSend ($tSessionID;$tFrom;$tTo;$tSubject;$tPageName)
APP_BkMailSend est elle-même une autre sous-méthode pour APP_BKExecute qui construit la chaîne de
commandes à envoyer par e-mail. Dans notre exemple, la page qui est envoyée est la page
"Mail_example.htm". Cette page devrait être dans votre boutique démo, car elle est inclue dans le dossier
DEMO_Site.
II Mettre à jour ou synchroniser les articles d’un serveur 4D Business Kit
Ajouter un Client dans 4D Business Kit
L’application Démo contient quatre tables : Customer, Product, Order, et Order_idem. Si vous avez créé une
boutique, la première des choses à faire est d’exporter vos clients vers 4D Business Kit.
Base Démo, choisissez "Customers" dans le menu "File". Dans le formulaire Liste de cette table choisissez
le bouton "New" pour ajouter un enregistrement. Saisissez les informations concernant votre client et cliquez
sur "Update BK". Un point d’arrêt a été placé par défaut, vous devriez donc voir apparaître la fenêtre du
mode Trace. Passez en pas en pas.
Vous verrez que la méthode nommée APP_BKCustomerUpdate est appelée. Passez dans cette méthode.
Deux autres méthodes sont appelées APP_BKSessionID et APP_BKExecute, décrites ci-dessous.
Comme APP_BKExecute , APP_BKSessionID est une sous-méthode, cette fois pour 4DBK_SessionNew
et 4DBK_SessionOpen mentionnées plus haut. Cette sous-méthode vous évite d’avoir à saisir à chaque fois
l’adresse IP et le numéro de port de Business Kit. Par défaut, cette méthode utilise l’adresse IP et le port
indiqués dans le dialogue des Préférences. APP_BKSessionID retournera aussi toujours l’ID de la session
courante active et créera une nouvelle session si celle-ci n’existe pas.
La première chose que fait APP_BKCustomerUpdate est de vérifier si le client existe dans Business Kit.
retournera une ou plusieurs informations pour ce marqueur 4DBKCustomerExists. L’une d’entre elles est
"CUS_UNK", Customer Unknown. Cette valeur est vérifiée avec les lignes de codes ci-dessous :
S i (APP_t_BkResult= "CUS_UNK")
$tCommand :=$tCommand+ "4DBKRecordNew/CUS ;"
Fin de si
Si le client est inconnu, les commandes qui mettront à jour les valeurs des différents champs du client seront
précédées par "4DBKRecordNew/CUS".
Comme vous pourrez le constater si vous lisez cette méthode, la mise à jour des valeurs dans les champs se
fait par l’appel de la commande 4DBKFieldSet avec le nom du champs à renseigner, par exemple :
$tCommand := "4DBKFieldSet/CusLastName="+[Customer]Name_Last
Ajouter un Produit dans 4D Business Kit
Pour ajouter un élément dans votre boutique, choisissez "Products" dans votre base DEMO. Une liste vide
se présente à vous. Cliquez sur "New" pour saisir un nouveau produit. Saisissez quelques informations,
rajoutez une image, et lorsque vous êtes prêts, cliquez sur le bouton "Update BK".
Par défaut, un point d’arrêt a été placé dans la procédure, donc vous arrivez dans le Mode Trace. Ce bouton
appelle une procédure APP_BKProductsUpdate. Cette méthode de haut niveau, appelle les méthodes
4DBK_ItemUpdateBuild et 4DBK_ItemUpdateSend. Ces deux méthodes mettent à jour les informations
d’un produit pour sa vente.
Ces méthodes envoient les informations sur le produit dans un Blob, en utilisant la méthode
4DBK_ItemUpdateBuild. Une fois que toutes les données sont stockées dans le Blob, on peut les envoyer
à 4D Business Kit avec la commande 4DBK_ItemUpdateSend. Il est intéressant de noter que la commande
4DBK_ItemUpdateSend ne nécessite pas d’indiquer l’ID de la session 4D BK ? seulement les quatre
caractères du code de la boutique, l’adresse IP de Business Kit, le numéro de port, et l’ID de l’élément que
vous souhaitez mettre à jour. En construisant le Blob comme une chaîne de commandes, vous pouvez aussi
envoyer des données binaires à 4D BK, principalement les images.
Ajouter un Produit dans le Caddy
Également dans le formulaire Entrée du Produit, vous avez un bouton appelé "Add to Cart". Cliquez dessus
Le formulaire Entrée Produit contient également un bouton "checkout". Il validera la commande et videra le
caddie de son contenu. La première chose à faire est de vérifier si le caddie contient des éléments :
$tCommand := "4DBKSelectionSet/B ;4DBKSelectionSize"
$iResult := APP_BKExecute ($tSessionID;$tCommand;->APP_t_BkResult)
Si un élément est présent, une seule méthode s’exécute via APP_BKExecute : 4DBKOrderValidate
Le cookie Business Kit
(cette partie concerne les solutions qui font adresser les pages dynamiques par le composant 4D BK)
Il peut y avoir de nombreuses raisons pour lesquelles vous souhaitez déployer 4D Business Kit avec une
application 4D; par exemple pour rajouter des fonctionnalités non-disponibles dans 4D BK. Pour cela vous
avez besoin que votre application 4D accède à la même session de données stockées dans 4D Business Kit.
4D Business Kit génère un cookie http pour chaque navigateur qui se connecte à une page générée par 4D
BK. Ce cookie est joint à chaque requête du navigateur vers 4D BK. Ceci permet à 4D BK de reconnaître
chaque internaute avec lequel il dialogue.
Pour que vos applications 4D et 4D BK travaillent en tandem, les deux doivent être adressés dans le même
domaine. Le mécanisme du cookie http permet de travailler de façon à ce qu’un cookie soit envoyé avec
chaque requête http à n’importe quel hôte (ordinateur) dans un domaine particulier. Cela signifie qu’une fois
que le cookie est mis en place, il sera envoyé à votre application 4D chaque fois que le navigateur fait une
requête. Votre application peut alors accéder à la session existante 4D BK.
Par défaut, un cookie est mis en place pour l’hôte à chaque requête http. Par exemple, si vous demandez un
document de "bktest.4D.com", le cookie sera mis en place pour ce serveur, et sera envoyé à l’hôte "bktest"
dans le domaine "4d.com". Il est possible de mettre en place un cookie pour un domaine entier, et si la
programmation en est faite, le cookie sera envoyé automatiquement avec chaque requête à n’importe quel
hôte du domaine.
Pour permettre ce comportement dans 4DBK, vous devez changer des paramètres dans la mise en place de la
boutique. Allez dans le menu "Fichier", et choisissez "Boutiques…". Double-cliquez sur la Boutique
DEMO. Cliquez sur l’onglet "Web (2)"
Sur ce dialogue, vous verrez un champ "Restriction de domaine pour les sessions". Ici vous devez indiquer le
domaine pour lequel vous mettez en place le cookie. Si votre domaine est "4d.com", vous devez saisir
".4d.com" (attention, il faut impérativement le point au début).
Ceci permet d’indiquer clairement à 4D BK que le cookie sera envoyé à n’importe quel hôte du domaine
"4d.com".
Il est important de noter que vos requêtes doivent être faites en utilisant le nom du domaine et non l’adresse
IP de l’ordinateur. Il est interdit de mettre en place un cookie pour un domaine en dehors des requêtes du
serveur web, qui peut être Business Kit, 4D, WebSTAR, Apache, etc. Si vous accédez à votre serveur 4D
BK grâce à l’adresse IP, quoique vous indiquiez dans la zone "Restriction de domaine…", cela n’aura aucun
effet. Même si votre ordinateur appartient au domaine spécifié, ce domaine doit être dans la requête http, une
adresse IP ne sera pas suffisante.
"hosts". Vous pouvez manuellement ajouter des hôtes et des domaines (n’importe quel hôte, n’importe quel
domaine) et une adresse IP correspondante à ce fichier. Ceci fonctionne parfaitement pour tester votre
application.
Exemple de fichier "hosts" sur un pc :
Pour garantir que le système du cookie fonctionne parfaitement, vous devez aller sur le dialogue "Web" des
paramétrages de la boutique et préciser que votre boutique répondra à l’adresse aux noms d’hôte et de
domaine indiqués. 4D Business Kit créera le lien pour vous si vous avez tout orthographié correctement.
Commencer une session
Pour vérifier comment votre application 4D et 4D Business Kit peuvent interagir, lancez votre navigateur et
connectez-vous à votre serveur 4D Business Kit
Si vous avez indiqué un hôte et un domaine personnel pour votre boutique, vous pouvez y accéder grâce à
l’URL. Par exemple si l’URL indiqué pour votre boutique est "bktest.4d.fr", vous tapez simplement cette
adresse.
La page d’accueil montrera tous les éléments de votre boutique DEMO. Si vous n’avez pas créé d’élément
dans votre boutique (soit directement, soit par l’intermédiaire de votre application 4D) vous ne pourrez rien
afficher. Dans ce cas, commencez par créer quelques enregistrements.
Si vous visualisez un article, cliquez sur celui-ci : il sera automatiquement ajouté au caddie qui est visualisé
sur la même page. Puis cliquez sur le lien "Sign In".Vous devrez saisir votre code d’utilisateur ([Customer]
ID) et votre mot de passe. Ces informations auront du être préalablement envoyées à la boutique. Le nom de
l’utilisateur apparaîtra alors sur l’Home Page.
Si vous recevez le bon message avec le cookie, votre page contient un bouton "Submit". Cliquez dessus.
Vous obtenez un message vous indiquant que votre commande est validée. Dans le cas contraire, vous
recevrez un message d’erreur, probablement du à une erreur d’identification.
Lorsque vous cliquez sur le bouton "Submit", la méthode APP_BKOrderComplete est appelée par la base
démo. Vous souhaiterez peut-être mettre un point d’arrêt dans cette méthode et l’appeler à nouveau. Notez
que chaque fois que vous l’appelez, le caddie est vidé car 4D BK vide les caddies chaque fois que la
commande est validée.
APP_BKOrderComplete commence par chercher le cookie 4D BK. Si elle le trouve, elle vérifie que le
cookie est authentifié ? ce qui est le cas si un utilisateur a saisi correctement son numéro et son mot de passe.
Ceci est déterminé par la méthode APP_BKCustomerLoggedIn. Voici la méthode qui conclut une simple
requête à 4DBK :
$tCommand := "4DBKField/CustomerLogged"
Si la session est authentifiée, la base demo cherchera le numéro d’utilisateur :
$tCommand := "4DBKField/CusCode"
Une fois l’utilisateur identifié, un appel est fait à APP_BKGetPage. Cette méthode demandera à 4D BK
d’envoyer une page spécifique et retournera les informations dans la base démo. La page en question est
appelée "Order_complete.htm" et contient de nombreux marqueurs 4D BK qui compléteront la commande et
renverront les informations à la base DEMO. Voici le contenu du fichier "Order_complete.htm":
<html>
<!--#4DBKStoreSet/DEMO-->
<!--#4DBKSelectionSet/B-->
<item_count><!--#4DBKSelectionSize--></item_count>
<item_list>
<!--#4DBKRecordSet/1-->
<!--#4DBKLoop/VL01,1,4DBKSelectionSize-->
<!--#4DBKIf(4DBKRecordExists)-->
<item>
<shipping><!--#4DBKField/PrShippingEXV--></shipping>
<order_date><!--#4DBKToday,mm-dd-yyyy--></order_date>
<subtotal><!--#4DBKField/PrItemsEXV--></subtotal>
<total><!--#4DBKField/PrOrderINV--></total>
<!--#4DBKOrderValidate-->
<order_code><!--#4DBKOrderCode--></order_code>
</html>
Ce fichier contient donc certains tags (marqueurs) 4D BK. Ces tags créeront une page contenant tous les
éléments du caddy de l’utilisateur. Tous les éléments sont inclus avec leurs propres marqueurs, sur le
principe d’XML. Ces marqueurs sont analysés par la méthode APP_BKOrderComplete, utilisant la
méthode GEN_StringTagValue. Il y a de nombreuses façons de délimiter champs et valeurs dans une page
de réponse. Cette méthode est seulement une possibilité parmi d’autres.
La commande et les données de cette méthode sont analysées d’après la réponse que la base démo reçoit. Les
enregistrements sont créés et sauvegardés en local dans la base, vous permettant ainsi d’y appliquer le
traitement souhaité, comme créer des bons de livraisons, faire des statistiques, etc.
Chargement d’une carte de crédit
Pour que 4D BK charge une carte de crédit, vous devez disposer d’un compte avec un organisme de paiement
comme Verisign, Authorize.net ou PayPal. Vous devez saisir les informations sur cet organisme au niveau de
la boutique dans la page "Services":
Dans notre exemple, le [Login] et le [Password] ont été saisis pour Authorize.net. Par défaut, la base DEMO
est mise en place pour utiliser Authorise.net comme organisme de paiement. Pour utiliser un autre organisme
(comme Verisign), allez dans le dialogue "Préférences" (menu "Fichier"), vous y trouverez un champ
appelé "BK Payment Config" dont la valeur est "AuthorizeNet_ADC.txt". Changez cette valeur pour la
configuration de paiement par carte que vous souhaitez utiliser. Vous trouverez ces différents fichiers texte
dans le répertoire suivant :
%BKInstall%/Services/Payments/CreditCard/ (ou 4DBK:Services:Payments:CreditCard sur Mac)
où %BKInstall% est le dossier 4D Business Kit principal.
Notez que vous pouvez créer votre propre fichier de services de paiement très facilement.
Vous ne pourrez continuer les manipulations dans cette section de la présente note technique que si vous
possédez un compte avec un organisme de paiement. Si vous n’en avez pas, il est toutefois possible
d’obtenir un compte de test avec l’organisme.
Une fois que vos services de paiement sont configurés, vous pouvez continuer. Retournez dans l’application
DEMO. Dans le menu "File", choisissez "Orders". Votre commande s’affiche dans la liste. Double-cliquez
sur cet enregistrement pour obtenir le formulaire de saisie.
Vous noterez une zone sur le formulaire appelé "Credit Card Interface". Ici vous pouvez saisir un numéro de
carte et un mois et année d’expiration. Vous devez saisir un numéro et une date d’expiration valide
(4444333322221111 est un bon numéro pour le test).
Cliquez alors sur le bouton "Charge Credit Card". À nouveau la fenêtre du débuggeur apparaît. Un point
d’arrêt a été placé juste avant l’appel à la méthode APP_BkOrderCharge. Passez pas à pas sur la méthode
pour voir comment elle fonctionne. Pour sa majeure partie, elle sert à vérifier la validité des données et si tout
semble correct, elle fait un appel à 4DBKCreditCartProcess à travers APP_BKExecute.
III Déléguer en local l’exécution de certaines taches internes du serveur 4DBK
Le plus souvent quand vous utilisez le composant 4D IP, la communication entre votre base 4D et 4D
Business Kit est initiée par votre propre base. Mais 4D Business Kit permet de déléguer le calcul du prix
d’un article ou des frais des modes d’expédition en utilisant le composant 4D IP. Voici un exemple :
Pour déléguer ces calculs, allez dans l’onglet "appels ext." de la boutique.
Si vous souhaitez déléguer un calcul, 4D Business Kit appellera votre base chaque fois qu’il en aura besoin. Il
exécutera la méthode par un appel standard 4DACTION. Le 4DACTION appellera soit la méthode
4DBKPrice soit 4DBKShipping. Ces méthodes sont installées avec le composant IP. Contrairement à
d’autres méthodes, celles-ci sont publiques. C’est-à-dire que vous pourrez les modifier (et ce sera nécessaire)
pour mettre en place vos propres calculs. Cela signifie aussi que votre application doit avoir son serveur Web
activé.
Conclusion
4D Business Kit est un puissant logiciel de e-commerce. Déployez votre propre application 4D en parallèle,
vous permet de construire rapidement de puissantes applications web et client/serveur. Le composant IP 4D
BK vous procure un outil qui vous apporte une grande souplesse dans le traitement des informations de
votre boutique 4D BK.