ONYX - 9.0 - Utilisation - Les bonnes pratiques/en

Différence entre versions

De MappingDoc
(Page créée avec « ===Installing the server=== * '''Using the local loop''': With the exception of special cases, the IP address of the Mapping server defined during installation must always... »)
 
(22 révisions intermédiaires par 2 utilisateurs non affichées)
Ligne 4 : Ligne 4 :
  
  
===Configuration du serveur===
+
===Configuring the server===
* '''Nettoyage et purge''' : Se reporter au guide d'exploitation afin de mettre systématiquement en place une stratégie de nettoyage et de purge des travaux, des fichiers temporaires, et des fichiers de logs.
+
* '''Cleaning and purging''': Refer to the operating guide to set up a systematic cleaning and purging strategy for jobs, temporary files, and log files.
  
  
===Interface d'administration===
+
===Admin interface===
* '''Paramétrer des bannières d'identification :''' Jusqu'à la version 8.0 de Mapping, il était vivement recommandé de modifier le fichier Haut.html et index.html afin d'ajouter une bannière permettant d'identifier visuellement l'environnement Mapping courant.<br/>
+
* '''Configuring identification banners:''' Up to version 8.0 of Mapping, it was strongly recommended to modify the files Haut.html and index.html in order to add a banner to identify the current Mapping environment visually.<br/>
:Depuis ONYX 9.0, ces bannières se paramètrent directement dans le mapping.conf via GUI_DISPLAY_ENVIRONMENT_LABEL et GUI_DISPLAY_ENVIRONMENT_COLOR.
+
:As of ONYX 9.0, these banners are set up directly in the mapping.conf via GUI_DISPLAY_ENVIRONMENT_LABEL and GUI_DISPLAY_ENVIRONMENT_COLOR.
  
  
 
===Designer===
 
===Designer===
* '''Nom des projets''' : FORMAT_SEQUENCE (exemple : FACTURES_00010.mpp).<br/>
+
* '''Name of the projects''': SEQUENCE_FORMAT (example : INVOICESS_00010.mpp).<br/>
:Un éventuel complément commentaire peut être ajouté à la suite (exemple : FACTURES_00010_Factures-Clients.mpp). Mais dans tous les cas, il est important que les 20 premiers caractères du nom du projet soient discriminants.
+
:An additional comment can be added afterwards (example: INVOICES_00010_Customer-Invoices.mpp). But in any case, it is important that the first 20 characters of the project name be discriminating.
:Une bonne pratique consiste à créer un sous-dossier par projet, contenant les fichiers sources du Designer et de Connect, les composants, les éléments variables et les fichiers txt ou xml d'exemple.
+
:Best practice: It is recommended that you create one sub-folder per project, containing the Designer and Connect source files, components, variable elements and example txt or xml files.
  
* '''Pas de calculs''' : Eviter de faire des calculs directement dans M-Designer. Privilégier les '''calculs en amont''' (ERP, M-Connect...)
+
* '''No calculations''': Avoid making calculations directly in M-Designer. Prefer making '''prior calculations''' (ERP, M-Connect...)
  
* '''Zones mémoire TEXTE''' : Si aucun calcul n'est requis, les zones de type "Mémoire" doivent toujours être de sous-type '''"Mémoire Texte"''' et jamais "Mémoire Entier" ni "Mémoire Flottant" (même si les champs manipulés sont numériques)
+
* '''TEXT memory zones''': If no calculations are required, "Memory" type zones must always have a '''"Text Memory"''' sub-type, never an "Entire Memory" nor "Floating Memory" (even if the fields handled are numerical)
  
* '''Espacement AVANT''' : Lors de la création de groupes, gérer les sauts de lignes avec les '''espacements AVANT'''. Les espacements APRES ne doivent être utilisés que pour ajouter un espace libre avant l'impression de la ligne suivante. Ne jamais écrire dans un espace réservé par une autre ligne (c-a-d par la ligne précédente ou par la ligne suivante), chaque ligne ayant son propre espace défini par <u><i>"Espacement AVANT + Espacement APRES"</i></u>.
+
* '''Space BEFORE''': when creating groups, manage line breaks with '''Space BEFORE'''. AFTER spacing should only be used to add an empty space before the next line. Do not ever write in a space dedicated to an other line (i.e the previous or next line), each line has its own dedicated space defined by <u><i>"Space BEFORE + Space AFTER"</i></u>.
  
* '''Sauts de pages automatiques''' : Ne jamais utiliser plus d'un groupe pouvant générer un saut de page dans un projet (même avec des conditions de d'exécution).
+
* '''Automatic page break''': Do not ever use more than one group to generate a page break in a project (even with execution conditions).
  
  
 
===Connect===
 
===Connect===
* '''MAPPING_DATASTREAM=XML''' : Pour générer un fichier XML, il faut impérativement créer la variable '''DB.MAPPING_DATASTREAM''' et lui affecter la valeur "XML"
+
* '''MAPPING_DATASTREAM=XML''': To generate an XML file, you must create the '''DB.MAPPING_DATASTREAM''' variable and associate the "XML" value to it.
  
* '''Génération automatique de projets XML''' : Il est déconseillé d'utiliser la fonctionnalité de génération automatique de projets prenant en charge des fichiers XML en entrée. Le code généré est en effet complexe à maintenir. Il peut néanmoins être utilisé pour comprendre les principes de fonctionnement de CONNECT sur la lecture de fichiers XML.
+
* '''Generating XML projects automatically''': Using the feature to generate projects automatically while supporting XML input files is not recommended. The code which is generated is difficult to maintain. It can however be used to understand CONNECT operating principles on XML files reading.
  
  
 
===Workflow===
 
===Workflow===
* '''Dev, recette et prod identique''' : Il est vivement conseillé de mettre en place des workflows 100% identiques entre les environnements de dev, de recette et de production. Les différences de traitements doivent être s'appuyer sur des paramètres d'environnement définis dans le fichier mapping.conf
+
* '''Identical integration, validation and production environment''': Implementing 100% identical workflows in the integration, validation and production environment is strongly recommended. The differences in processing must be based on environmental parameters defined in the mapping.conf file.
  
  
 
===Spooler===
 
===Spooler===
  
* '''Files d'attente dédiées''' : Créer des files d'attentes dédiées dès qu'il y a une communication avec l'extérieur (envoi par email, ftp etc...). Le traitement associé ne doit rien faire d'autre que cette communication, avec éventuellement quelques variables (SetParam) et des conditions. Mais ne jamais cumuler un traitement de fichiers (Connect, composition, manipulation de fichiers XPS...) et un envoi de mail ou dépôt ftp dans la même file d'attente.
+
* '''Dedicated queues''': Whenever external communication is involved (documents sent by e-mail, ftp etc...), a dedicated queue can be created. The processing associated with this communication must not handle anything else, except for potential variables (SetParam) and conditions. Do not combine a file processing (Connect, mapping, XPS file management) with e-mail delivery or ftp deposit, in the same queue.
  
* '''Traitements continus sans intervention''' : En général, les files d'attente qui exécutent des traitements (workflow, Shell etc...) devront être configurée afin de continuer le traitement des travaux suivants en cas d'erreur. La valeur par défaut (default) étant "Stop", ce qui provoque un arrêt des traitements en cas d'échec, nécessitant un acquittement de la part d'un utilisateur.
+
* '''Autonomous continuous processings''': Queues which manage processings (workflow, Shell etc...) usually need to be configured to keep processing the following jobs in the event of an error. The default value (default) is "Stop", this stops processings in case of technical failure, the user then needs to intervene.
  
* '''Conserver les travaux :''' Ne pas oublier de "Conserver" les travaux envoyés dans les files d'attente à des fins de debug.
+
* '''Save jobs:''' Do not forget to "Save" the jobs sent to the queues for debugging purposes.
  
* '''Niveau de log''' : Pour des raisons de performances de traitements des travaux, ne jamais laisser le paramètre '''LOG_LEVEL''' à 4 en production. Sauf éventuellement si les performances ne sont pas un besoin majeur. Ce paramètre a énormément d'impacts sur les performances s'il y a beaucoup de "petits" travaux" à traiter. Dans ce cas, le niveau 3 peut également être trop élevé, et le niveau 2 peut s'avérer suffisant (uniquement erreurs et warnings).
+
* '''Log level''': For performance reasons, do not leave the '''LOG_LEVEL''' setting set to 4 in production. You could leave it the way it is if performance is not one of your major concerns. This setting has huge impacts on performance if many "small" jobs are processed. In this case the log level 3 can also be too high, level 2 can be enough (only for errors and warnings).
  
  
===Robots Scan Folder===
+
===Scan Folder Robots===
* '''Injection systématique dans une file d'attente''' : Sauf cas particuliers, il ne faut JAMAIS associer un robot scanfolder à un workflow "complexe". Le seul traitement pouvant être exécuté par le workflow est l'injection du travail dans une file d'attente du spooler, et éventuellement des initialisions de variables permettant d'ajouter des méta données à ce travail. Ceci pour des raisons de suivi des travaux ainsi que pour bénéficier d'une gestion correcte des exceptions.
+
* '''Automatic queue assignment''': Except in special cases, you should NEVER associate a scanfolder robot with a "complex" workflow. The only processing the workflow can execute is assigning a job to the spooler queue, and potentially initiate variables to add meta data to this job. The aim is to track jobs and benefit from proper exception management.
  
* '''Répertoires locaux seulement''' : Il est vivement déconseillé de faire pointer un robot Scan folder sur un répertoire distant situé sur un serveur distant.
+
* '''Local folders only''': Setting a Scan folder robot to point in a remote folder on a remote server is not recommended.
  
* '''Intégrité de transfert''' : Il est primordial de mettre en place une stratégie de dépôt cohérente afin que Mapping ne puisse pas récupérer des fichiers tronqués car en cours de transfert (ftp, sftp, cft ou autres protocoles). Par exemple avec un nom temporaire pendant le dépôt, avec un fichier "témoin" ou en déplaçant le fichier (dans le même FS) une fois le transfert terminé. Ne pas utiliser le paramètre "CHECK_FTP_FILE_ACCESS" et son timeout qui ne permet en aucun cas de garantir l'intégrité du fichier récupéré.
+
* '''Transfer integrity''': Establishing a coherent deposit strategy is essential so that Mapping cannot retrieve truncated files being transferred (ftp, sftp, cft or other protocoles). For example, use a temporary name for the time of the deposit, use a "cookie" file or move the file (in the same FS) once the transfer is finished. Do not use the "CHECK_FTP_FILE_ACCESS" setting and its timeout as it does not insure the integrity of the file retrieved.
  
===Envoi d'emails===
+
===Sending e-mails===
* '''Séparer éclatement et envoi''' : Ne pas utiliser les outils permettant de faire à la fois l'éclatement d'un fichier d'impression ET l'envoi des emails dans le même traitement. En effet, il est préférable de faire d'abord l'éclatement en PDF vers une file d'attente dédiée à l'envoi d'email, puis que cette file d'attente se charge à son tour d'envoyer les emails de façon unitaire.<br/>
+
* '''Separate splitting and sending''': Do not use tools to split, print files and send e-mails all in the same processing. Prefer splitting in PDF into a dedicated e-mailing queue first, then in turn let this queue manage e-mail delivery, one e-mail at a time.<br/>
:Dans le cas contraire, aucun suivi d'envoi n'est possible et si par exemple une adresse email est fausse (erreur de syntaxe), le travail peut être interrompu en cours de traitement alors qu'une partie des emails a déjà été envoyée. Il est alors impossible de relancer proprement le travail sans générer de doublons d'emails.
+
:Otherwise, no tracking is possible and if, for example, an email address is inaccurate (syntax error), the job can be interrupted during processing even though some of the e-mails have already been sent. Relaunching the job properly is then impossible without generating duplicate e-mails.
 
 
 
 
 
 
<!-- Best practice // Best practices -->
 

Version actuelle datée du 28 août 2019 à 13:37

Autres langues :
English • ‎français

Installing the server

  • Using the local loop: With the exception of special cases, the IP address of the Mapping server defined during installation must always be 127.0.0.0.1 or localhost. These addresses are always true, even if the Mapping environment is migrated to another server, or if its IP address changes.


Configuring the server

  • Cleaning and purging: Refer to the operating guide to set up a systematic cleaning and purging strategy for jobs, temporary files, and log files.


Admin interface

  • Configuring identification banners: Up to version 8.0 of Mapping, it was strongly recommended to modify the files Haut.html and index.html in order to add a banner to identify the current Mapping environment visually.
As of ONYX 9.0, these banners are set up directly in the mapping.conf via GUI_DISPLAY_ENVIRONMENT_LABEL and GUI_DISPLAY_ENVIRONMENT_COLOR.


Designer

  • Name of the projects: SEQUENCE_FORMAT (example : INVOICESS_00010.mpp).
An additional comment can be added afterwards (example: INVOICES_00010_Customer-Invoices.mpp). But in any case, it is important that the first 20 characters of the project name be discriminating.
Best practice: It is recommended that you create one sub-folder per project, containing the Designer and Connect source files, components, variable elements and example txt or xml files.
  • No calculations: Avoid making calculations directly in M-Designer. Prefer making prior calculations (ERP, M-Connect...)
  • TEXT memory zones: If no calculations are required, "Memory" type zones must always have a "Text Memory" sub-type, never an "Entire Memory" nor "Floating Memory" (even if the fields handled are numerical)
  • Space BEFORE: when creating groups, manage line breaks with Space BEFORE. AFTER spacing should only be used to add an empty space before the next line. Do not ever write in a space dedicated to an other line (i.e the previous or next line), each line has its own dedicated space defined by "Space BEFORE + Space AFTER".
  • Automatic page break: Do not ever use more than one group to generate a page break in a project (even with execution conditions).


Connect

  • MAPPING_DATASTREAM=XML: To generate an XML file, you must create the DB.MAPPING_DATASTREAM variable and associate the "XML" value to it.
  • Generating XML projects automatically: Using the feature to generate projects automatically while supporting XML input files is not recommended. The code which is generated is difficult to maintain. It can however be used to understand CONNECT operating principles on XML files reading.


Workflow

  • Identical integration, validation and production environment: Implementing 100% identical workflows in the integration, validation and production environment is strongly recommended. The differences in processing must be based on environmental parameters defined in the mapping.conf file.


Spooler

  • Dedicated queues: Whenever external communication is involved (documents sent by e-mail, ftp etc...), a dedicated queue can be created. The processing associated with this communication must not handle anything else, except for potential variables (SetParam) and conditions. Do not combine a file processing (Connect, mapping, XPS file management) with e-mail delivery or ftp deposit, in the same queue.
  • Autonomous continuous processings: Queues which manage processings (workflow, Shell etc...) usually need to be configured to keep processing the following jobs in the event of an error. The default value (default) is "Stop", this stops processings in case of technical failure, the user then needs to intervene.
  • Save jobs: Do not forget to "Save" the jobs sent to the queues for debugging purposes.
  • Log level: For performance reasons, do not leave the LOG_LEVEL setting set to 4 in production. You could leave it the way it is if performance is not one of your major concerns. This setting has huge impacts on performance if many "small" jobs are processed. In this case the log level 3 can also be too high, level 2 can be enough (only for errors and warnings).


Scan Folder Robots

  • Automatic queue assignment: Except in special cases, you should NEVER associate a scanfolder robot with a "complex" workflow. The only processing the workflow can execute is assigning a job to the spooler queue, and potentially initiate variables to add meta data to this job. The aim is to track jobs and benefit from proper exception management.
  • Local folders only: Setting a Scan folder robot to point in a remote folder on a remote server is not recommended.
  • Transfer integrity: Establishing a coherent deposit strategy is essential so that Mapping cannot retrieve truncated files being transferred (ftp, sftp, cft or other protocoles). For example, use a temporary name for the time of the deposit, use a "cookie" file or move the file (in the same FS) once the transfer is finished. Do not use the "CHECK_FTP_FILE_ACCESS" setting and its timeout as it does not insure the integrity of the file retrieved.

Sending e-mails

  • Separate splitting and sending: Do not use tools to split, print files and send e-mails all in the same processing. Prefer splitting in PDF into a dedicated e-mailing queue first, then in turn let this queue manage e-mail delivery, one e-mail at a time.
Otherwise, no tracking is possible and if, for example, an email address is inaccurate (syntax error), the job can be interrupted during processing even though some of the e-mails have already been sent. Relaunching the job properly is then impossible without generating duplicate e-mails.