Connecteurs

beCPG fournit un ensemble de connecteurs pour exporter les données du PLM vers différents formats et systèmes externes. Les connecteurs sont des applications Spring Boot qui peuvent être exécutées en mode autonome, en mode planifié ou dans un pipeline Spring Cloud Dataflow.

Connecteurs disponibles

Prérequis

Avant de commencer, assurez-vous d'avoir installé :

• Java 17 ou version ultérieure
• Accès à une instance beCPG avec des identifiants valides
• Pour les connexions HTTPS avec certificats auto-signés, voir Annexe 1 : Installation du certificat

Versions

Compatibilité avec beCPG

Cette documentation couvre la nouvelle génération de connecteurs (version 4.x). La compatibilité avec les versions de beCPG est la suivante :

Note : Pour les versions de beCPG antérieures à 4.2.3, seul le Mode Canal est supporté.

Connecteurs legacy

Pour les versions de beCPG antérieures à 23.4.2, veuillez consulter la documentation des connecteurs legacy.

Configuration commune

Cette section couvre les options de configuration partagées par tous les connecteurs beCPG.

Installation

1. Demandez l'archive de distribution du connecteur au support beCPG (ex: becpg-csv-connector-x.x.x-distribution.zip)
2. Téléchargez et décompressez l'archive du connecteur
3. Configurez le fichier application.properties dans le dossier config

Exécution du connecteur

Linux

./becpg-connector.sh

Windows

Double-cliquez sur becpg-connector.bat

Docker

docker run --rm -v "$PWD":/usr/becpg-connector -v "$PWD"/data:/usr/becpg-connector/data -w /usr/becpg-connector/data \
   openjdk:17 java -Dfile.encoding=UTF8 \
   -jar /usr/becpg-connector/lib/becpg-connector.jar --spring.profiles.active=sample

Maven

mvn spring-boot:run -Dspring-boot.run.arguments=--spring.profiles.active=dev

Méthodes de configuration

1. Utilisation de application.properties

Utilisez le fichier application-sample.properties dans le dossier config comme modèle. Renommez-le en application-{profil}.properties.

2. Gestion des profils

Créez plusieurs fichiers application-{profil}.properties pour différentes configurations. Spécifiez le profil au démarrage :

--spring.profiles.active=sample

3. Surcharge des paramètres

Les paramètres peuvent être surchargés directement dans le script de démarrage avec l'option Java -D :

java -Dcontent.service.url=https://server.becpg.local:443 \
     -Dconnector.dest.path="./data" \
     -jar ./lib/becpg-connector.jar --spring.profiles.active=sample

4. Via les canaux de publication beCPG

Les connecteurs peuvent être configurés directement dans l'interface beCPG :

1. Allez dans Administration beCPG → Éditer : Caractéristiques
2. Sélectionnez Canaux de publication dans le panneau de gauche
3. Ajoutez ou modifiez un canal et fournissez la configuration au format JSON :

{
  "properties": {
    "connector.notify.enabled": false,
    "connector.notify.from": "support@becpg.fr",
    "connector.notify.to": "ops@becpg.fr"
  }
}

Connexion au serveur (Obligatoire)

content.service.url=https://votre-instance-becpg:443
content.service.security.basicAuth.username=utilisateur
content.service.security.basicAuth.password=motdepasse

Chemin de destination (Obligatoire)

connector.dest.path=.

Attention : Sous Windows, utilisez C:\\Temp\\becpg-connector ou C:/Temp/becpg-connector

Sélection des entités

Les connecteurs fonctionnent selon deux modes : Mode Requête ou Mode Canal.

Mode Requête

Activé si connector.query.template est défini. Utilise une requête de recherche où %s est remplacé par la date du dernier import réussi (stockée dans le fichier lastImport).

connector.query.template=(@cm\\:created:[%s TO MAX] OR @cm\\:modified:[%s TO MAX]) AND ( ASPECT:\"bcpg:productAspect\" OR TYPE:\"bcpg:client\" OR TYPE:\"bcpg:supplier\" )

Mode Canal

Mode par défaut si aucun modèle de requête n'est fourni. Les entités sont sélectionnées dans beCPG en les ajoutant au Canal de publication correspondant.

connector.channel.id=votre-id-canal

Extraction des données

Les champs à extraire sont définis via trois propriétés principales :

remote.fields=bcpg:eanCode,cm:title,bcpg:legalName
remote.lists=bcpg:allergenList,bcpg:ingList
remote.params={"appendCode":false,"appendNodeRef":false}

Vous pouvez également définir des champs et listes supplémentaires :

remote.extra.fields=ca:customfield1,ca:customfield2
remote.extra.lists=testList,exampleList

Protocoles de livraison

Définis via connector.send.protocol. Plusieurs protocoles peuvent être utilisés (séparés par des virgules) : local, ftp, ftps, sftp, remote.

connector.send.protocol=local,sftp
connector.send.deleteOnSuccess=false

Configuration SFTP

connector.send.sftp.host=
connector.send.sftp.port=22
connector.send.sftp.login=
connector.send.sftp.password=
connector.send.sftp.destFolder=

Configuration locale

connector.send.local.destFolder=

Configuration distante

connector.send.remote.destNodeRef=workspace://SpacesStore/XXX

Notifications

connector.notify.enabled=true
connector.notify.from=support@becpg.fr
connector.notify.to=admin@company.com

spring.mail.host=localhost
spring.mail.port=25
spring.mail.username=
spring.mail.password=
spring.mail.properties.mail.smtp.auth=true
spring.mail.properties.mail.smtp.starttls.enable=true

Actions post-connecteur

Exécutez des actions après l'exécution du connecteur :

connector.channel.onSuccess.remote={"attributes": {"bcpg:productState": "Simulation"}}
connector.channel.onError.remote=

Formatage général

connector.decimalFormat=#.####
connector.dateFormat=dd/MM/yyyy
connector.field.assocSeparator=|

Débogage

logging.level.fr.becpg.connector=INFO
logging.level.fr.becpg.connector.readers=DEBUG
logging.level.fr.becpg.connector.writer=DEBUG
logging.level.fr.becpg.connector.notifiers=DEBUG

Ou via la ligne de commande :

-Dconnector.debug.level=debug

Configuration SSL

Désactiver la vérification SSL (pour les tests uniquement) :

remote.ssl.trustAll=true

Compatibilité

Compresser les en-têtes lorsque la liste des champs est trop longue :

remote.compress.param=true

Mode planificateur

Exécuter le connecteur périodiquement selon une expression CRON :

spring.batch.job.enabled=false
connector.scheduler.enabled=true
connector.cron.expression=0 0/5 * * * ?

Configuration de sauvegarde

connector.dest.path.shouldCreateBackup=true

Connecteur CSV

Le connecteur CSV exporte les entités beCPG et leurs listes ou documents associés vers des fichiers CSV basés sur des mappings configurables.

Propriétés spécifiques CSV

Formats CSV

Pour plus de détails : https://commons.apache.org/proper/commons-csv/apidocs/org/apache/commons/csv/CSVFormat.html

Configuration du mapping

Via application.properties

Utilisez le préfixe mapping.csv.<typeEntité>. Par défaut, le nom du fichier correspond au type.

# Mapping basique
mapping.csv.bcpg_finishedProduct=bcpg:code,cm:name,cm:title

# Nom de fichier personnalisé
mapping.csv.bcpg_finishedProduct.fileName=Export_Produits

# En-têtes spécifiques
mapping.csv.bcpg_finishedProduct.headers=ID,Nom,Description

# Plusieurs fichiers pour le même type (indexés de 0 à 9)
mapping.csv.bcpg_finishedProduct.0.fileName=Fichier_1
mapping.csv.bcpg_finishedProduct.0=bcpg:code,cm:name
mapping.csv.bcpg_finishedProduct.1.fileName=Fichier_2
mapping.csv.bcpg_finishedProduct.1=bcpg:erpCode,cm:productUnit

# Mapper plusieurs types avec un alias
mapping.csv.bcpg_rawMaterial.alias=article
mapping.csv.bcpg_semiFinishedProduct.alias=article
mapping.csv.article=bcpg:code,cm:name,bcpg:productHierarchy1|bcpg:erpCode

Via fichier de mapping Excel

Définissez connector.csv.xlsxMapping=./config/mapping.xlsx. Chaque onglet représente un fichier CSV.

Exemple :

Configuration de l'export des champs

Champs imbriqués

Utilisez le pipe | pour exporter les propriétés des associations :

bcpg:productGeoOrigin|bcpg:geoOriginISOCodeNumeric

Champs multilingues

Ajoutez le code de langue après le nom du champ :

• cm:description_en : Description en anglais
• bcpg:legalName_ja_JP : Nom légal en japonais

Extraction de documents

Utilisez les préfixes doc, document ou share dans votre mapping :

• doc|<cheminSource>;<cheminDest> : Télécharge les documents correspondants. Colonne masquée dans le CSV
• document|<cheminSource>;<cheminDest> : Télécharge et écrit le chemin local dans le CSV
• share|<cheminSource> : Écrit une URL de partage publique dans le CSV

Exemple :

document|/Images/*.jpg;images/${entity.bcpg:code}-${document.cm:name}

Placeholders :

• ${entity|bcpg:code} : Valeur de propriété de l'entité
• ${document.cm:name} : Nom du document
• ${document.path} : Chemin du document
• ${document.id} : ID du document

Configuration de l'export des listes

Exportez les listes associées en définissant des mappings spécifiques. Les champs préfixés par entity| exportent les propriétés de l'entité principale.

mapping.csv.nutList=entity|bcpg:code,bcpg:nutListNut,bcpg:nutListValue,bcpg:nutListUnit
mapping.csv.packagingList=entity|bcpg:code,bcpg:packagingListProduct,bcpg:packagingListQty

Champs spéciaux des listes

Liste des nutriments

• nut["Code"] ou nut["Code"]("locale") : Obtenir les valeurs arrondies (ex: nut["ENER-KJO"]("EU"))
• Champs arrondis disponibles : roundedValue_locale, roundedSecondaryValue_locale, roundedValuePerServing_locale, roundedMini_locale, roundedMaxi_locale, roundedGDAPerc_locale, roundedValuePerContainer_locale, roundedGDAPercPerContainer_locale

Mapping requis :

mapping.csv.nutList=bcpg:nutListNut|gs1:nutrientTypeCode,bcpg:nutListRoundedValue

Liste des allégations

• claim[Code] : Renvoie "true" si les critères sont respectés (ex: claim[ORGANIC_GS1])

Mapping requis :

mapping.csv.labelClaimList=bcpg:lclLabelClaim|bcpg:labelClaimCode,bcpg:lclClaimValue,bcpg:lclComments

Liste des ingrédients

• ingLabelingList[label]|value : Renvoie l'étiquetage manuel si fourni, sinon le formulé
• ingLabelingList[label]|manualValue : Étiquetage manuel uniquement
• ingLabelingList[label]|formulatedValue : Étiquetage formulé uniquement

Par défaut, le HTML est supprimé. Ajoutez @ à la fin pour conserver le HTML.

Mapping requis :

mapping.csv.ingLabelingList=bcpg:illManualValue,bcpg:illValue,bcpg:illGrp|bcpg:lrLabel

Allergènes

• voluntaryAllergen / inVoluntaryAllergen : Noms légaux séparés par des virgules
• voluntaryAllergen|code / inVoluntaryAllergen|code : Codes séparés par des virgules
• voluntaryAllergen_en : Noms légaux en anglais

Mapping requis :

mapping.csv.allergenList=bcpg:allergenListAllergen|bcpg:allergenCode,bcpg:allergenListAllergen|bcpg:legalName,bcpg:allergenListVoluntary,bcpg:allergenListInVoluntary

Autres listes

• listName[0]|prop : Propriété de l'élément 0 dans la liste (ex: compoList[0]|bcpg:compoListQty)

Formules SpEL

Utilisez le préfixe formula| pour une logique complexe :

# Accès aux propriétés
formula|props["bcpg:erpCode"]

# Accès via associations (échapper | avec \\|)
formula|props["bcpg:clients\\|cm:title"]

# Logique conditionnelle
formula|props["qty"] != null ? props["qty"] / props["total"] : props["qty"]

# Formatage des nombres
formula|(new java.text.DecimalFormat("#.###")).format(props["qty"])

Pour plus d'informations : http://docs.spring.io/spring/docs/3.2.x/spring-framework-reference/html/expressions.html

Mapping de codes

Via application.properties

mapping.bcpg_productState.map=Valid|VALIDATED,Simulation|SIMULATION

Via fichier de mapping Excel

Ajoutez une feuille nommée Mapping :

Champs obligatoires

connector.csv.mandatoryFields=bcpg:useByDate,bcpg:unitPrice

Les entités sans ces champs ne seront pas extraites.

Plugin connecteur de documents

Activez le plugin d'extraction de documents :

connector.plugin.class=fr.becpg.connector.plugin.StandardDocumentVisitor

Configurez les mappings de documents :

mapping.document.bcpg_finishedProduct=/Images/produit.jpg|img_${bcpg:erpCode}.jpg;/Documents/${cm:name} - Fiche Technique.pdf|FT_${bcpg:erpCode}.pdf

Format : <chemin source>|<chemin destination> séparés par ;

Plugin connecteur de workflows

Exportez les workflows et leurs tâches au format CSV :

connector.plugin.class=fr.becpg.connector.plugin.WorkflowCSVVisitor

Mappings disponibles :

mapping.csv.workflow_instances=id,name,title,description,isActive,startDate,priority,message,endDate,dueDate,initiator.userName
mapping.csv.workflow_tasks=workflowInstance|id,workflowInstance|name,id,state,name,title,description,bpm:completionDate,bpm:workflowDueDate

Filtrer les workflows :

connector.query.template=startedAfter=%sZ

Valeurs de filtre possibles : state, initiator, priority, dueBefore, dueAfter, definitionId, definitionName, startedBefore, startedAfter, completedBefore, completedAfter, exclude

Plugin connecteur multiniveau

Extrayez les entités avec leurs listes de données de composition en format multiniveau :

connector.plugin.class=fr.becpg.connector.plugin.MultiLevelCSVVisitor

Ce plugin extrait la composition d'un produit semi-fini dans un produit fini ou la composition d'un produit semi-fini dans un autre produit semi-fini et ainsi de suite. Il permet également de voir le niveau de chaque composant.

Exemple - Composition d'un produit fini :

Fonctionnalités

• Extrait la composition des produits semi-finis dans les produits finis
• Affiche le niveau de chaque composant
• Calcule les quantités au niveau du produit
• Calcule les valeurs d'emballage (produits par PCB, colis par palette à chaque niveau)
• Calcule la quantité d'emballage utilisée pour chaque produit
• Extrait les caractéristiques dynamiques (préfixées par dyn_)

Exemple : La propriété "qty multiniveau" devient dyn_qty_multiniveau

Pour plus d'informations sur les caractéristiques dynamiques, voir Formulation de recette - Caractéristiques formulées.

Calcul des quantités

Le niveau du semi-fini C est égal à 3. Pour calculer sa quantité au niveau du produit, nous devons d'abord calculer la quantité du semi-fini B au niveau du produit en utilisant une règle de trois :

QTE Semi-fini B = (Poids Semi-fini B / Poids Semi-fini A) * Poids Semi-fini A au niveau produit

• Poids du semi-fini A = somme de ses composants (trouvée dans les caractéristiques formulées)

• QTE Semi-fini B = (0,31 / 0,66) × 5 = 2,348 kg

Ce résultat est la quantité que vous utiliserez pour calculer la quantité du semi-fini C, et ainsi de suite à chaque fois que vous descendez dans le niveau de composition.

Exemple détaillé :

• Quantité du semi-fini B au niveau du produit => après calcul = 2,348 kg
• Poids du semi-fini B = 0,17 kg
• Quantité du semi-fini C utilisée dans la composition du semi-fini B = 0,1 kg
• La quantité du semi-fini C utilisée au niveau du produit = (0,1 / 0,17) × 2,348 = 1,381 kg

Le raisonnement est le même pour calculer la quantité de matière première au niveau du produit.

Configuration

Comme dans le connecteur standard, pour activer le connecteur multiniveau :

connector.plugin.class=fr.becpg.connector.plugin.MultiLevelCSVVisitor

Le plugin étant dédié aux produits finis et semi-finis, les fichiers CSV ne fonctionneront pas avec les autres types d'entités (clients, fournisseurs, etc.). La requête de recherche doit être configurée en conséquence :

connector.query.template=(@cm\\:created:[%s TO MAX] OR @cm\\:modified:[%s TO MAX]) AND ( TYPE:\"bcpg:finishedProduct\" OR TYPE:\"bcpg:semiFinishedProduct\")

Connecteur GS1

Le connecteur GS1 exporte les produits beCPG vers GS1 GDSN XML (Catalogue Item Notification), avec livraison optionnelle vers Atrify ou Synkka.

Configuration spécifique GS1

Paramètres principaux

Paramètres avancés

Mapping de champs

Renommez les champs par environnement en utilisant des paires sourceQName|targetQName :

remote.fields=bcpg:eanCode,gs1:depth,gs1:width,gs1:height
remote.extra.fields=specific:depth,specific:width,specific:height
remote.fields.map=gs1:depth|specific:depth,gs1:width|specific:width,gs1:height|specific:height

Intégration Synkka

synkka.key=votre-cle-api-ici
synkka.baseUrl=https://api.synkka.example

Exemple de configuration

content.service.url=https://dev.becpg.fr:443
content.service.security.basicAuth.username=connector
content.service.security.basicAuth.password=secret

connector.channel.id=gs1
connector.dest.path=target/gs1

remote.gs1.locales.supported=fr,en
remote.gs1.providerName=beCPG
remote.gs1.providerGln=0000000000000
remote.gs1.senderGln=0000000000000
remote.gs1.receiverGln=0000000000000

remote.fields=bcpg:eanCode,cm:description,gs1:depth,gs1:width,gs1:height

Pour le mapping détaillé des champs, consultez le fichier MAPPING.md dans la distribution du connecteur.

Connecteur Equadis

Le connecteur Equadis exporte les produits beCPG vers Equadis au format XML.

Configuration spécifique Equadis

Format du nom de fichier

Pattern : products_<code>_<ddMMyy_HHmm>.xml

• <code> : bcpg:erpCode si présent, sinon le code de l'entité

Conventions de mapping

Le connecteur utilise un fichier de mapping Excel avec les sections HEADER et COLUMNS.

Chemins d'en-tête

Pattern : parent1/parent2/.../FIELDID

Préfixes et suffixes spéciaux

• #MULTI : Préfixe sur un FIELDID pour itérer sur un tableau
• #MULTIGROUP : Préfixe sur un parent pour créer des groupes répétables
• @<lang> : Suffixe sur les IDs de champ pour ajouter un attribut de langue

Exemple de mapping

Pour le mapping détaillé des champs, consultez le fichier MAPPING.md dans la distribution du connecteur.

Connecteur Salsify

Le connecteur Salsify exporte les produits de beCPG vers Salsify (SupplierXM) via l'API publique Salsify.

Configuration spécifique Salsify

Paramètres API

GS1 et localisation

Champs supplémentaires

Le connecteur peut envoyer des champs spécifiques même s'ils sont absents dans beCPG :

• remote.salsify.rulesActivate, remote.salsify.rulesDesactivate
• remote.salsify.scaleDescriptionText, remote.salsify.incotermCode
• remote.salsify.palletpackagingTypeCode, remote.salsify.palletIsOrderableUnit
• remote.salsify.ownerMarketGLN, remote.salsify.ownerMarketName
• remote.salsify.depthProduct, remote.salsify.widthProduct, remote.salsify.heightProduct

Templates et mapping

Le rendu JSON utilise des templates FreeMarker. Assurez-vous que vos remote.fields correspondent au template et à votre modèle de données Salsify.

Mappings de champs clés

• bcpg:eanCode, cm:title, gs1:functionalName, cm:description
• Flags d'unité : gs1:isTradeItemABaseUnit, gs1:isTradeItemAConsumerUnit
• Dimensions/poids : gs1:depth, gs1:width, gs1:height, bcpg:netWeight
• Marchés cibles : gs1:targetMarkets|gs1:targetMarketCountries
• Allergènes/ingrédients/nutrition : bcpg:allergenList*, bcpg:ingList*, bcpg:nutList*

Déploiement Docker

FROM eclipse-temurin:17-jre
WORKDIR /app
COPY target/becpg-salsify-connector-*.jar app.jar
ENV JAVA_OPTS=""
ENTRYPOINT ["sh","-c","java $JAVA_OPTS -jar /app/app.jar"]

docker run --rm \
  -e REMOTE_SALSIFY_CLIENT_ID=XXXXX \
  -e REMOTE_SALSIFY_CLIENT_SECRET=YYYYY \
  -e SPRING_PROFILES_ACTIVE=dev \
  becpg-salsify-connector:local

Pour le mapping détaillé des champs, consultez le fichier MAPPING.md dans la distribution du connecteur.

Dépannage

Problèmes courants

• Aucun fichier généré : Vérifiez connector.channel.id et que le canal retourne des entités
• Échecs d'authentification : Vérifiez les identifiants content.service.security
• Fichier non écrit : Vérifiez les permissions de connector.dest.path
• En-têtes manquants/dupliqués : Si HEADER est défini dans Excel, le writer ne génère pas automatiquement depuis COLUMNS
• Échec d'extraction de document : Confirmez le format cheminSource;cheminDest et vérifiez les logs

Gestion des erreurs

• Tentatives automatiques : Maximum 3 tentatives sur les timeouts réseau
• Récupération d'erreur : Les erreurs de traitement d'entités individuelles n'échouent pas le batch entier
• Validation : Validation du schéma avant écriture/envoi

Annexe 1 : Installation du certificat (Windows)

Récupération du certificat du serveur beCPG :

Étape 1. Sur Firefox, cliquez sur l'icône du cadenas

Étape 2. Cliquez sur la flèche à droite du statut de connexion

Étape 3. Cliquez sur "Plus d'informations"

Étape 4. Cliquez sur "Afficher le certificat"

Étape 5. Allez dans la section "Divers" et téléchargez le certificat PEM (cert)

Étape 6. Sauvegardez le fichier dans un dossier sur votre ordinateur

Ouvrez un terminal dans votre dossier Java.

Note : Il peut être nécessaire d'ouvrir un terminal avec les droits administrateur. Cherchez "cmd" dans la barre de recherche Windows, clic droit et sélectionnez "Exécuter en tant qu'administrateur".

Naviguez vers le dossier Java avec la commande cd. Exemple avec un dossier Java situé à C:\Program Files\Java\jre1.8.0_241.

Vérifiez que bin\keytool et lib\security\cacerts existent dans le dossier Java.

Une fois le terminal ouvert, utilisez la commande suivante :

bin\keytool -import -alias {nom_certificat} -file {chemin_fichier_pem} -keystore lib\security\cacerts

Exemple avec un certificat nommé becpg.pem situé dans C:\tmp avec l'alias becpg :

bin\keytool -import -alias becpg -file C:\tmp\becpg.pem -keystore lib\security\cacerts

Le mot de passe par défaut est : changeit

Suivez les étapes affichées par le terminal. Une fois installé, vérifiez l'installation :

bin\keytool -list -v -alias becpg -keystore lib\security\cacerts