Notes sur le Service / Produit CRM

::: note ::: title Remarque :::

Pour un guide complet de bout en bout couvrant la définition des produits, la fourniture, les addons et la déprovisionnement avec des exemples Ansible détaillés et une stratégie de tarification, consultez le Guide complet du cycle de vie des produits. :::

Aperçu des Produits et Services

Produit (Élément de Menu) :

Un Produit est comme un plat spécifique sur un menu de restaurant, tel qu'un "Spaghetti Carbonara."

Il a une description claire, une liste d'ingrédients (comme des pâtes, de la crème, des œufs, du fromage et du bacon), et un prix.

Dans OmniCRM, un Produit contient également les détails de ce qui est inclus --- fonctionnalités, spécifications et tarification.

Souvent, les clients peuvent vouloir des modifications, comme "sans oignons" ou "ajouter du fromage supplémentaire" à leur repas. Dans OmniCRM, cela correspond à la personnalisation d'un service avant sa création. Le niveau de personnalisation ou de modifications d'un service dépend de vous (l'opérateur) à définir.

Dans OmniCRM, les clients ou le personnel peuvent modifier un Produit pour mieux répondre aux besoins d'un client spécifique, comme améliorer leur vitesse Internet ou ajouter des fonctionnalités spécifiques. Cette personnalisation est reflétée dans le Service spécifique fourni.

Un produit est essentiellement une offre que les clients peuvent choisir de commander, similaire à lire et choisir un plat sur le menu.

Catalogue de Produits (Menu du Restaurant) :

Le Catalogue de Produits est comme l'ensemble du menu dans un restaurant, qui liste tous les plats disponibles --- des entrées aux desserts.

C'est la collection complète de tout ce que le restaurant (ou dans votre cas, le Fournisseur de Services) a à offrir.

Dans le contexte commercial, le Catalogue de Produits fournit aux clients tous les Produits disponibles, afin qu'ils puissent choisir celui qui répond le mieux à leurs besoins.

Service (Plat Préparé) :

Lorsque un client commande un article du menu, le plat est préparé dans la cuisine. Cela revient à créer un Service à partir d'un Produit.

Dans OmniCRM, lorsque un client sélectionne un Produit, une instance de ce Produit est créée et livrée en tant que Service.

Il est personnalisé et préparé spécifiquement pour ce client, tout comme un repas préparé pour un convive.

Par exemple, lorsque quelqu'un sélectionne le "Plan Internet Bronze" dans le Catalogue de Produits, le système de fourniture "cuisine" une instance de ce plan à partir des ingrédients (adresses IP, modems et ports) --- c'est-à-dire, active le plan et le livre au client spécifique.

Produits Groupés (Repas Combiné) :

Le Catalogue de Produits peut également offrir des forfaits, comme un repas combiné qui inclut une entrée, un plat principal et un dessert ensemble pour un prix spécial.

Dans OmniCRM, les Produits groupés combinent plusieurs Produits individuels en un seul package pratique --- comme un "Forfait Essentiels à Domicile" qui inclut des services Internet, câble et téléphone à un tarif réduit.

Une fois sélectionné, ce forfait est transformé en plusieurs Services adaptés au client.

Définitions de Produit

Un produit est un modèle utilisé pour créer un service / addon / remise / option supplémentaire, etc.

Dans la définition, nous incluons :

• Informations sur le produit (caractéristiques, inclusions, T&Cs, durée du contrat, icône, etc.) qui sont affichées à l'utilisateur du CRM (Client ou Personnel).

• La logique commerciale autour de qui peut acheter le produit (Commercial ou Résidentiel), s'il dépend d'un service parent provisionné (comme des addons mobiles uniquement disponibles pour les clients ayant un service mobile), s'il peut être commandé directement par un client via l'auto-assistance ou uniquement par un agent du service client, et quand le produit peut être acheté (permettant à un produit d'être disponible uniquement pour une période déterminée).

• Lorsque des éléments d'inventaire doivent être inclus (comme des modems ou des cartes SIM), ceux-ci sont spécifiés comme une Liste d'Éléments d'Inventaire, par exemple, le service ci-dessous nécessite une carte SIM et un numéro de téléphone à attribuer :

  ['SIM Card', 'Phone Number'] Ceux-ci correspondent aux Éléments d'Inventaire définis dans le CRM.

• Référence à un Playbook Ansible pour provisionner le service Provisioning Play ainsi que les variables à passer à Ansible. Ces variables à passer sont magiques, en ce sens qu'elles peuvent être des variables comme service_id qui sont définies par le produit auquel nous l'ajoutons, ou elles peuvent être comme ICCID & MSISDN où nous avons sélectionné des éléments d'inventaire qui sont transmis lors de l'attribution de l'inventaire. Le regroupement est géré dans le playbook de provisionnement pour contenir plusieurs services, par exemple, un produit groupé Internet à domicile, TV & Voix, peut provisionner un service pour chacun.

Catégories de Produits et Types de Services

Les produits utilisent deux champs de classification pour aider à organiser et filtrer les offres :

Catégories de Produits

Le champ category contrôle où les produits sont affichés dans l'interface utilisateur. Les valeurs courantes incluent :

• standalone - Affiché comme une option de service de base lors de la création d'un nouveau service
• addon - Affiché lors de l'ajout à un service existant
• bundle - Affiché comme une option de service groupé (provisionné comme un addon aux services existants)
• promo - Offres promotionnelles spéciales

Ces catégories sont purement organisationnelles et ne dictent pas ce qui est provisionné. Le comportement de provisionnement réel est entièrement déterminé par le playbook Ansible référencé dans provisioning_play.

Par exemple : - Un produit standalone crée généralement un nouvel objet de service - Un produit addon ou bundle est généralement ajouté à un service existant - Mais cela dépend de l'implémenteur écrivant le playbook - vous pourriez créer plusieurs objets de service à partir d'un addon, ou modifier des services existants à partir d'un produit autonome si nécessaire

La catégorie contrôle simplement le flux de l'interface utilisateur et où les clients/le personnel voient l'option de produit.

Types de Services

Le champ service_type catégorise quel type de service est fourni.

Ces types sont entièrement définis par l'utilisateur, mais les valeurs courantes incluent :

• mobile - Services de téléphonie mobile avec voix, SMS et données
• fixed - Services Internet fixes sans fil ou câblés
• fixed-voice - Services de voix fixe (VoIP, ligne fixe)
• hotspot - Dispositifs de point d'accès mobile ou de location
• dongle - Services de modem USB ou dongle
• voice - Services uniquement vocaux
• data - Services uniquement de données

Comme les catégories, les types de services sont personnalisables en fonction de vos offres. Ils aident à :

• Filtrer quels addons s'appliquent à quels services de base
• Organiser les produits dans le portail client
• Correspondre aux exigences d'inventaire
• Déterminer les flux de travail de provisionnement

Exemple : Un client avec un service mobile peut voir des addons mobiles, tandis qu'un client avec un service fixed voit des addons de ligne fixe.

Gestion des Produits

Les produits sont gérés via la page de Gestion des Produits, où vous pouvez voir, rechercher, filtrer et éditer tous les produits disponibles.

{.align-center width="800px"}

Interface Modale de Produit

Cliquer sur n'importe quel produit ouvre une interface à onglets améliorée qui organise tous les paramètres du produit en groupes logiques pour une navigation et une édition plus faciles.

{.align-center width="800px"}

La modale de gestion des produits comprend cinq onglets organisés :

1. 📋 Informations de Base - Informations de base sur le produit (nom, slug, catégorie, icône, caractéristiques, conditions)
2. 💰 Tarification - Tous les champs liés aux coûts, y compris les coûts récurrents, les coûts d'installation et le pourcentage de taxe
3. ⚙️ Configuration - Paramètres de renouvellement, types de clients et dépendances
4. 🔧 Provisionnement - Configuration du playbook Ansible et exigences d'inventaire
5. 📅 Disponibilité - Plages de dates et horodatages système

{.align-center width="800px"}

Organisation de l'Onglet Tarification :

L'onglet Tarification regroupe les champs de coût en sections logiques :

• Coûts Récurrents - Coûts de détail et de gros mensuels côte à côte
• Coûts d'Installation - Frais d'activation uniques pour le détail et le gros
• Taxe - Configuration du pourcentage de taxe avec calcul automatique

Fonctionnalités du Mode Édition :

• Sélecteur d'Icône - Rechercher et sélectionner visuellement des icônes FontAwesome
• Sélecteur d'Éléments d'Inventaire - Sélectionner parmi les types d'éléments d'inventaire disponibles
• Sélecteur de Date/Heure - Sélection facile des fenêtres de disponibilité
• Formatage de Devise - Préfixe automatique $ pour les champs de coût
• Sélecteurs Déroulants - Options prédéfinies pour les catégories et les champs booléens

{.align-center width="800px"}

Sélecteur d'Icône :

Lors de l'édition du champ d'icône, une interface de sélection d'icônes recherchable apparaît, vous permettant de parcourir visuellement et de sélectionner parmi des milliers d'icônes FontAwesome.

{.align-center width="800px"}

Fonctionnalités : * Rechercher des icônes par mot-clé (par exemple, "clé à molette", "mobile", "wifi") * Prévisualiser l'apparence de l'icône en temps réel * Affiche le nom de la classe d'icône pour référence * Sélection déroulante pour un accès rapide

Onglet Configuration :

L'onglet Configuration organise les paramètres de comportement du produit en groupes logiques.

{.align-center width="800px"}

Sections de Configuration :

• Paramètres de Renouvellement :
  • Renouvellement Automatique - Comportement de renouvellement par défaut (Demander/Oui/Non)
  • Autoriser le Renouvellement Automatique - Si les clients peuvent activer le renouvellement automatique
  • Jours de Contrat - Durée minimale du contrat (par exemple, 30 pour mensuel, 365 pour annuel)
• Types de Clients :
  • Résidentiel - Disponible pour les clients consommateurs
  • Commercial - Disponible pour les clients commerciaux
• Dépendances :
  • Liste de Dépendances - Identifiants de produit ou types de service requis avant que ce produit puisse être ajouté
  • Utilisé pour les dépendances d'addon (par exemple, les addons mobiles nécessitent un service mobile actif)

Onglet Provisionnement :

L'onglet Provisionnement gère l'automatisation Ansible et les exigences d'inventaire.

{.align-center width="800px"}

Champs de Provisionnement :

• Play de Provisionnement :
  • Nom du playbook Ansible (sans extension .yaml)
  • Doit exister dans le répertoire OmniCRM-API/Provisioners/plays/
  • Appelé lorsque le service est créé, mis à jour ou déprovisionné
• Variables JSON de Provisionnement :
  • Variables par défaut passées au playbook Ansible sous forme de JSON
  • Peuvent être remplacées lors du provisionnement
  • Le playbook reçoit celles-ci plus customer_id, product_id, service_id, access_token
• Liste d'Éléments d'Inventaire :
  • Sélecteur multi-choix montrant les types d'éléments d'inventaire disponibles
  • Exemples : Carte SIM, Numéro de Téléphone, Modem Routeur, Adresse IPv4
  • Le client/le personnel sélectionne des éléments spécifiques de l'inventaire disponible lors de la commande
  • Les identifiants d'inventaire sélectionnés sont passés au playbook avec le type d'inventaire comme nom de variable

Onglet Disponibilité :

L'onglet Disponibilité contrôle quand le produit peut être acheté et affiche les métadonnées système.

{.align-center width="800px"}

Paramètres de Disponibilité :

• Disponible À Partir de :
  • Date/heure à laquelle le produit devient disponible à l'achat
  • Laisser vide pour une disponibilité immédiate
  • Utile pour préannoncer de nouveaux produits
• Disponible Jusqu'à :
  • Date/heure à laquelle le produit n'est plus disponible à l'achat
  • Laisser vide pour une disponibilité indéfinie
  • Parfait pour les promotions à durée limitée ou les produits en fin de vie
• Métadonnées Système (Lecture Seule) :
  • Créé - Horodatage lorsque le produit a été créé pour la première fois
  • Dernière Modification - Horodatage de la mise à jour la plus récente
  • Maintenu automatiquement par le système

Actions Modales :

• Mode Vue :
  • Fermer - Rejeter la modale
  • Cloner le Produit - Créer une copie avec le suffixe "_clone"
  • Éditer le Produit - Passer en mode édition
• Mode Édition/Création :
  • Annuler - Jeter les modifications et fermer
  • Enregistrer les Modifications - Créer ou mettre à jour le produit (gros bouton pour accentuer)

Champs de Produit

Le modèle de Produit contient toutes les informations nécessaires pour définir une offre et comment elle doit être provisionnée. Ces champs sont gérés via l'interface modale de gestion des produits décrite ci-dessus.

Informations de Base

• product_id - Identifiant unique automatiquement attribué par le système
• product_name - Nom affiché aux clients et au personnel dans l'interface utilisateur
• product_slug - Identifiant unique utilisé dans les URL et les appels API (minuscules, sans espaces, utiliser des tirets)
• category - Contrôle où ce produit apparaît dans l'interface utilisateur :
  • standalone - Affiché comme une option de service de base lors de la création d'un nouveau service
  • addon - Affiché lors de l'ajout à un service existant
  • bundle - Affiché comme une option de service groupé
  • promo - Offres promotionnelles spéciales
• service_type - Type de service fourni (par exemple, mobile, fixe, voix fixe, point d'accès, dongle, voix, données). Utilisé pour filtrer quels addons s'appliquent à quels services.
• comment - Notes internes sur le produit pour référence du personnel uniquement (non affichées aux clients)
• icon - Classe d'icône FontAwesome affichée dans l'interface utilisateur (par exemple, fa-solid fa-sim-card)

Champs de Tarification

• retail_cost - Charge récurrente mensuelle facturée au client (définie à 0 pour les achats uniques ou les produits prépayés)
• wholesale_cost - Votre coût mensuel pour fournir ce service (utilisé pour les calculs de marge)
• retail_setup_cost - Frais d'activation ou d'installation uniques facturés au client
• wholesale_setup_cost - Votre coût unique pour la mise en place du service
• tax_percentage - Pourcentage de taxe appliqué à ce produit (par exemple, 10 pour 10 %, 12,5 pour 12,5 %). Défini à 0 pour les produits exonérés de taxe. Ce taux de taxe est automatiquement appliqué aux transactions créées à partir de ce produit.

{.align-center width="800px"}

Application de la Taxe :

Lorsqu'une transaction est créée à partir de ce produit, le pourcentage de taxe est automatiquement copié dans la transaction et le montant de la taxe est calculé. Par exemple :

• Produit avec 10 % de taxe, $50,00 coût de détail → La transaction a $5,00 de taxe
• Produit avec 0 % de taxe (exonéré de taxe) → La transaction a $0,00 de taxe
• Remplacement manuel de la transaction → Le personnel peut changer le pourcentage de taxe par transaction

Visibilité et Accès Client

• enabled - Si ce produit est actif et disponible à l'achat (défini sur false pour masquer sans supprimer)
• residential - Si les clients résidentiels (consommateurs) peuvent acheter ce produit
• business - Si les clients commerciaux peuvent acheter ce produit
• customer_can_purchase - Si les clients peuvent acheter eux-mêmes via le portail (true) ou si seul le personnel peut l'ajouter (false)
• available_from - Date/heure à laquelle ce produit devient disponible à l'achat (optionnel)
• available_until - Date/heure à laquelle ce produit n'est plus disponible à l'achat (optionnel, utile pour les offres à durée limitée)

Contrat et Renouvellement

• contract_days - Durée minimale du contrat en jours (par exemple, 30 pour mensuel, 365 pour annuel, 0 pour aucun contrat minimum)
• auto_renew - Comportement de renouvellement par défaut :
  • prompt - Demande au client à chaque fois s'il souhaite renouveler
  • true - Renouvelle automatiquement sans demander
  • false - Nécessite un renouvellement manuel
• allow_auto_renew - Si les clients peuvent activer le renouvellement automatique (défini sur false pour les achats uniques)

Contenu Visible par le Client

• terms - Conditions affichées aux clients avant l'achat (inclure des limitations, des règles d'expiration, des conditions d'utilisation)
• features_list - Liste des caractéristiques et inclusions affichées aux clients (format de liste Python : ['Feature 1', 'Feature 2'])

Configuration de Provisionnement

• provisioning_play - Nom du playbook Ansible qui provisionne ce service (sans extension .yaml). Doit exister dans le répertoire OmniCRM-API/Provisioners/plays/.
• provisioning_json_vars - Variables par défaut passées au playbook Ansible sous forme de JSON. Celles-ci peuvent être remplacées lors du provisionnement. Le playbook reçoit celles-ci avec customer_id, product_id, service_id et access_token.
• inventory_items_list - Liste des éléments d'inventaire requis pour ce produit (par exemple, ['SIM Card', 'Mobile Number']). Lorsqu'un client commande, il sera invité à sélectionner des éléments spécifiques de l'inventaire disponible. Les identifiants d'inventaire sélectionnés sont passés au playbook avec le type d'inventaire comme nom de variable.
• relies_on_list - Liste des identifiants de produit ou des types de service qui doivent exister avant que ce produit puisse être ajouté. Utilisé pour les dépendances d'addon (par exemple, les addons mobiles nécessitent un service mobile actif).

Métadonnées Système

• created - Horodatage lorsque le produit a été créé (défini automatiquement)
• last_modified - Horodatage de la dernière mise à jour (mis à jour automatiquement)

Exemples de Définitions de Produits

Produit Autonome (Carte SIM Mobile)

{
  "product_id": 1,
  "product_slug": "Mobile-SIM",
  "product_name": "Mobile SIM Only",
  "category": "standalone",
  "service_type": "mobile",
  "provisioning_play": "play_psim_only",
  "provisioning_json_vars": "{\"iccid\": \"\", \"msisdn\": \"\"}",
  "inventory_items_list": "['SIM Card', 'Mobile Number']",
  "retail_cost": 0,
  "retail_setup_cost": 0,
  "wholesale_cost": 3,
  "wholesale_setup_cost": 1,
  "contract_days": 0,
  "residential": true,
  "business": true,
  "enabled": true,
  "customer_can_purchase": true,
  "icon": "fa-solid fa-sim-card",
  "features_list": "['Australian Phone Number (04xxx)', 'Fastest speeds', 'Best coverage', 'Roaming on the Mainland']",
  "terms": "Must be activated within 6 months. All credit lost if service is not used for 12 months.",
  "comment": "Physical SIM card for use with Mobile Phones"
}

Ce produit autonome nécessite deux éléments d'inventaire (Carte SIM et Numéro de Téléphone) et crée un nouveau service lorsqu'il est provisionné.

Produit Addon (Plan de Données Mensuel)

{
  "product_slug": "norfone-mobile-prepaid-mini",
  "product_name": "Norfone Mini Plan",
  "category": "addon",
  "service_type": "mobile",
  "provisioning_play": "play_topup_charge_then_action",
  "provisioning_json_vars": "",
  "inventory_items_list": "[]",
  "retail_cost": 30,
  "retail_setup_cost": 0,
  "wholesale_cost": 5.84,
  "contract_days": 30,
  "residential": true,
  "business": false,
  "enabled": true,
  "customer_can_purchase": true,
  "auto_renew": "prompt",
  "icon": "fa-solid fa-sim-card",
  "features_list": "['8GB of Ultra fast data', 'Unlimited Calls & Texts to Norfone users', '100 Minutes of Talk to Australia', '100 SMS to Australia', '30 Day Expiry']",
  "terms": "Credit expires after 30 days. Once data, voice or sms is used up, you will need to top up to continue using the service.",
  "comment": "Our smallest plan for light users"
}

Ce produit addon ne nécessite pas d'inventaire et est appliqué à un service existant. Il facture le client et ajoute des crédits/soldes à leur service.

Produit Groupé (Forfait Seniors)

{
  "product_slug": "Bundle-Seniors",
  "product_name": "Seniors Bundle",
  "category": "bundle",
  "service_type": "fixed",
  "provisioning_play": "play_seniors_package",
  "provisioning_json_vars": "{\"IPTV_Service_ID\": \"SeniorBundle\"}",
  "inventory_items_list": "['Modem Router']",
  "retail_cost": 30,
  "retail_setup_cost": 0,
  "wholesale_cost": 10,
  "wholesale_setup_cost": 11,
  "contract_days": 180,
  "residential": true,
  "business": false,
  "enabled": true,
  "icon": "fa-solid fa-person-walking-with-cane",
  "features_list": "['20Mbps Download', '5Mbps Upload', 'Unlimited Data', 'Home Voice', 'TV: Extra +£5 per month', '£60 Installation Fee']",
  "terms": "6 Month Contract, must show senior citizen's card to qualify",
  "comment": "20Mbps/2Mbps GPON Service + IPTV + Phone"
}

Ce produit groupé provisionne plusieurs services (Internet + IPTV + Téléphone) en utilisant un seul playbook. Il nécessite un élément d'inventaire (Modem Routeur).

Produit Addon (Recharge Simple)

{
  "product_slug": "Mobile-Topup-5",
  "product_name": "PAYG £5 Topup",
  "category": "addon",
  "service_type": "mobile",
  "provisioning_play": "play_topup_monetary",
  "provisioning_json_vars": "{\"service_id\": \"\"}",
  "inventory_items_list": "[]",
  "retail_cost": 5,
  "retail_setup_cost": 0,
  "wholesale_cost": 0,
  "contract_days": 0,
  "residential": true,
  "business": false,
  "enabled": true,
  "customer_can_purchase": true,
  "icon": "fa-solid fa-coins",
  "features_list": "['£5 credit', 'Valid for 180 days']",
  "terms": "Valid for 180 days or until all credit is used. See our website for full rates",
  "comment": "£5 to use for Calls, SMS & Data"
}

Cet addon ajoute simplement un crédit monétaire à un service existant. Aucun inventaire requis, et il utilise service_id pour identifier quel service recharger.

Comment les Variables sont Passées à Ansible

Comprendre comment les variables circulent de la définition du produit à travers l'API jusqu'au playbook Ansible est essentiel pour écrire des playbooks de provisionnement efficaces.

Sources et Fusion des Variables

Lorsqu'un travail de provisionnement est créé, les variables proviennent de plusieurs sources et sont fusionnées dans cet ordre (les sources ultérieures remplacent les précédentes) :

1. Variables de provisioning_json_vars du Produit - Variables par défaut de la définition du produit
2. Corps de la demande - Variables passées dans l'appel API (peuvent remplacer les valeurs par défaut du produit)
3. Variables ajoutées par le système - Ajoutées automatiquement par le système de provisionnement
4. Sélections d'inventaire - Identifiants des éléments d'inventaire sélectionnés (si inventory_items_list n'est pas vide)

Processus de Fusion des Variables

Le système fusionne les variables de toutes les sources, les sources ultérieures remplaçant les précédentes. Cela permet une personnalisation flexible au moment du provisionnement.

Par exemple, si votre produit a :

"provisioning_json_vars": "{\"monthly_cost\": 50, \"data_gb\": 100}"

Et votre demande API inclut :

{
  "product_id": 10,
  "customer_id": 456,
  "monthly_cost": 45,
  "custom_param": "value"
}

Les extra_vars finales passées à Ansible seront :

{
    "monthly_cost": 45,        # Remplacé par la demande
    "data_gb": 100,            # Provenant de provisioning_json_vars
    "product_id": 10,          # Provenant de la demande
    "customer_id": 456,        # Provenant de la demande
    "custom_param": "value",   # Provenant de la demande
    "access_token": "eyJ..."   # Ajouté par le système
}

Variables Ajoutées par le Système

Le système de provisionnement ajoute automatiquement :

• access_token - Jeton JWT pour authentifier les appels API de retour au CRM (provenant de g.access_token pour l'authentification IP/API key, ou généré à partir de refresh_token pour l'authentification utilisateur)
• initiating_user - L'identifiant de l'utilisateur qui a déclenché le provisionnement (ou le premier administrateur pour les systèmes automatisés)
• Tous les champs du corps de la demande (product_id, customer_id, service_id, etc.)

Variables d'Inventaire

Lorsqu'un produit nécessite des éléments d'inventaire (par exemple, inventory_items_list: "['SIM Card', 'Mobile Number']"), le processus fonctionne comme suit :

1. UI/API invite à la sélection - L'utilisateur sélectionne des éléments d'inventaire spécifiques parmi le stock disponible
2. Identifiants d'inventaire ajoutés aux variables - Les identifiants des éléments d'inventaire sélectionnés sont ajoutés avec le type d'inventaire comme nom de variable
3. Le playbook accède aux identifiants d'inventaire - Le playbook de provisionnement peut alors récupérer les détails complets de l'inventaire à partir de l'API CRM

Par exemple, si un utilisateur sélectionne : - Carte SIM avec inventory_id : 789 - Numéro de Téléphone avec inventory_id : 101

Les variables passées au playbook incluent : - SIM Card: 789 - Mobile Number: 101

Le playbook peut alors utiliser ces identifiants pour récupérer les enregistrements d'inventaire complets (ICCID, IMSI, MSISDN, etc.) à partir de l'API CRM et utiliser ces informations pour provisionner le service sur l'équipement réseau.

Comment Ansible Reçoit les Variables

Le système de provisionnement passe toutes les variables fusionnées au playbook Ansible en tant que extravars. À l'intérieur du playbook, ces variables sont disponibles via le système de variables standard d'Ansible et peuvent être utilisées dans les tâches.

Les variables peuvent être référencées directement dans les tâches du playbook en utilisant la syntaxe {{ variable_name }}. Par exemple, {{ product_id }}, {{ customer_id }}, {{ monthly_cost }}, etc.

Variables Passées aux Produits Addon

Lorsqu'un produit addon est provisionné, le système passe automatiquement :

• product_id - L'identifiant du produit addon en cours de provisionnement
• customer_id - Le client qui possède le service
• service_id - L'identifiant du service auquel cet addon est ajouté (critique pour les addons)
• access_token - Jeton d'authentification pour les appels API
• Toutes les variables de provisioning_json_vars
• Toutes les variables supplémentaires de la demande API

Exemple de Flux de Provisionnement d'Addon

Lorsqu'un client ajoute l'addon "Recharge de £5" à son service mobile (service_id : 123), le playbook reçoit des variables comprenant :

• product_id: 45 (le produit de recharge)
• customer_id: 456 (le client)
• service_id: 123 (le service auquel ajouter du crédit)
• access_token: Jeton d'authentification
• Plus toutes les variables de provisioning_json_vars du produit

Le playbook utilise ensuite ces variables pour :

1. Récupérer les détails du service à partir de l'API CRM en utilisant le service_id
2. Extraire l'UUID du service et d'autres informations de l'enregistrement du service
3. Ajouter du crédit au système de facturation (OCS) en utilisant l'UUID du service
4. Enregistrer la transaction dans le CRM à des fins de facturation

Ce flux permet à l'addon d'identifier exactement quel service modifier et d'appliquer les modifications de manière appropriée.

Différence entre les Variables de Produits Autonomes et Addon

Produits Autonomes reçoivent :

• product_id - Le produit en cours de provisionnement
• customer_id - Le client commandant le service
• Identifiants d'éléments d'inventaire (par exemple, SIM Card, Mobile Number) si le produit les nécessite
• access_token - Pour l'authentification API

Produits Addon reçoivent :

• product_id - Le produit addon en cours de provisionnement
• customer_id - Le client qui possède le service
• service_id - L'identifiant du service existant à modifier (c'est la clé de différence)
• access_token - Pour l'authentification API

La clé de différence est service_id - cela indique au playbook quel service existant modifier ou ajouter à.

Produits Groupés

Les produits groupés sont provisionnés comme des addons mais leur playbook peut créer plusieurs enregistrements de service. Ils reçoivent les mêmes variables que les addons, y compris :

• product_id - Le produit groupé
• customer_id - Le client
• service_id - Service parent (le cas échéant)
• Identifiants d'éléments d'inventaire (par exemple, Modem Router) si requis
• access_token - Pour l'authentification API

Le playbook groupé (par exemple, play_seniors_package) crée alors plusieurs services liés (Internet, IPTV, Téléphone) et les relie ensemble.

Services

Un service est une instance d'un produit qui appartient à un client, pour lequel il est facturé.

C'est essentiellement un lien vers un OCS (Système de Facturation en Ligne) qui gère la génération de charges et les soldes et utilisations réels du compte. L'OCS est alimenté par CGRateS et gère les soldes monétaires, les soldes unitaires (données, voix, SMS), les Plans d'Action pour le renouvellement automatique, et les Seuils pour les limites de dépenses.

Ajout d'un Service : Sélection et Filtrage des Produits

Lors de l'ajout d'un service à un client (soit un nouveau service autonome, soit un addon à un service existant), le système affiche les produits disponibles dans une interface en carrousel. Les produits affichés sont filtrés en fonction de plusieurs critères :

Filtrage des Produits pour les Services Autonomes

Lors de la création d'un nouveau service pour un client, l'interface utilisateur affiche des produits filtrés par :

1. Type de Client - Les produits sont catégorisés comme :
   • Individuel (Résidentiel) : Produits où residential = true ou business = false
   • Commercial : Produits où business = true
2. Catégorie - Les produits sont séparés en :
   • Plans de Service : Produits avec category = standalone ou bundle
   • Addons : Produits avec category = addon (affichés dans un carrousel séparé)
3. Disponibilité - Les produits ne sont affichés que si :
   • enabled = true - Le produit est actif et non désactivé
   • La date actuelle est entre available_from et available_until - Le produit est dans sa fenêtre de disponibilité
   • customer_can_purchase = true (si le client achète lui-même) - Le produit permet l'achat direct par le client

::: note ::: title Remarque :::

Filtrage au Niveau API : L'API filtre automatiquement les produits par statut activé et dates de disponibilité à deux niveaux :

• Points de Terminaison d'Achat/Sélection (/crm/product/) - Utilisé par la modale des Addons et la Liste des Plans pour la sélection de produits. Filtre automatiquement pour afficher UNIQUEMENT les produits activés dans leur plage de dates de disponibilité. Cela garantit que les clients et le personnel ne peuvent sélectionner que des produits actuellement disponibles à l'achat.
• Points de Terminaison de Gestion (/crm/product/paginated) - Utilisé par la page de Gestion des Produits. Affiche TOUS les produits, y compris ceux désactivés et en dehors des dates de disponibilité, permettant aux administrateurs de gérer l'ensemble du catalogue de produits, y compris les produits inactifs.

Passez include_disabled=true au point de terminaison de produit de base pour contourner le filtrage (uniquement pour un usage administratif). :::

L'interface utilisateur affiche des carrousels séparés pour :

• Plans de Service Individuels - Produits résidentiels pour les clients consommateurs
• Plans de Service Commercial - Produits commerciaux pour les clients commerciaux
• Addons Individuels - Packs d'addons résidentiels
• Addons Commercials - Packs d'addons commerciaux

Filtrage des Produits pour les Services Addon

Lors de l'ajout d'un addon à un service existant, un filtrage supplémentaire est appliqué :

1. Correspondance du Type de Service - Seuls les addons avec un service_type correspondant sont affichés :
   • Si le service existant a service_type = "mobile", seuls les addons avec service_type = "mobile" sont affichés
   • Cela garantit que les clients mobiles ne voient que des addons mobiles, les clients Internet ne voient que des addons Internet, etc.
2. Vérification des Dépendances - Si un addon a une relies_on_list :
   • Le système vérifie si le client a les produits/services requis
   • Seuls les addons dont les dépendances sont satisfaites sont affichés
3. Filtre de Type de Client Identique - Les addons sont toujours filtrés par residential contre business pour correspondre au type de client

Exemple de Scénario de Filtrage

Pour un client commercial avec un service mobile existant (service_type = "mobile"):

• Produits Autonomes Affichés : Tous les produits autonomes/groupés commerciaux (business = true, category != "addon")
• Produits Addon Affichés : Seulement des addons mobiles commerciaux (business = true, category = "addon", service_type = "mobile")
• Produits Cachés : Produits résidentiels, addons pour d'autres types de services (Internet, voix, etc.), produits désactivés

Champs de Service

Le modèle de Service contient des champs qui suivent l'instance de service provisionnée et sa relation avec le client, le produit et le système de facturation.

Informations de Base sur le Service

• service_id - Identifiant unique automatiquement attribué par le système (lecture seule)
• customer_id - Lien vers le client qui possède ce service (lecture seule après création)
• product_id - Lien vers le produit à partir duquel ce service a été créé (lecture seule après création)
• service_name - Nom affiché aux clients (modifiable)
• service_type - Type de service : mobile, internet, voip, iptv, bundle, etc. (modifiable)
• service_uuid - Identifiant unique utilisé dans OCS/CGRateS pour la facturation (lecture seule, auto-généré)
• icon - Classe d'icône FontAwesome pour affichage dans le portail d'auto-assistance (modifiable)

Statut et Dates du Service

• service_status - Statut actuel : Actif, Inactif, Suspendu, etc. (modifiable)
• service_provisioned_date - Date à laquelle le service a été provisionné pour la première fois (défini automatiquement, lecture seule)
• service_active_date - Date à laquelle le service est devenu actif (modifiable)
• service_deactivate_date - Date à laquelle le service expire ou sera désactivé (modifiable)
• contract_end_date - Date de fin de l'engagement contractuel (modifiable)

Facturation et Tarification

• retail_cost - Charge récurrente mensuelle au client (modifiable)
• wholesale_cost - Votre coût pour fournir le service (modifiable)
• service_billed - Si ce service apparaît sur les factures (modifiable, par défaut : vrai)
• service_taxable - Si des taxes s'appliquent à ce service (modifiable, par défaut : vrai)
• invoiced - Si le service a été facturé (défini automatiquement par le système de facturation)
• promo_code - Code promotionnel utilisé lors de la création du service (modifiable)

Visibilité Client

• service_visible_to_customer - Si le client peut voir ce service dans le portail d'auto-assistance (modifiable, par défaut : vrai)
• service_usage_visible_to_customer - Si le client peut voir les détails d'utilisation/solde (modifiable, par défaut : vrai)

Configuration de Provisionnement

• provisioning_play - Playbook Ansible utilisé pour provisionner ce service (hérité du produit, lecture seule)
• provisioning_json_vars - Variables passées au playbook de provisionnement (héritées du produit, lecture seule)
• deprovisioning_play - Playbook Ansible à exécuter lorsque le service est déprovisionné (lecture seule)
• deprovisioning_json_vars - Variables pour le playbook de déprovisionnement (lecture seule)

Relations de Service

• bundled_parent - Si ce service fait partie d'un bundle, l'identifiant du service parent (lecture seule)
• site_id - Lien vers le site/local physique où le service est livré (modifiable)

Notes et Métadonnées

• service_notes - Notes internes sur le service pour référence du personnel (modifiable)
• created - Horodatage lorsque le service a été créé (défini automatiquement, lecture seule)
• last_modified - Horodatage de la dernière mise à jour (mis à jour automatiquement, lecture seule)

Champs Modifiables vs Lecture Seule

Modifiables via API/UI :

Les services peuvent être mis à jour via PATCH /crm/service/{service_id} avec ces champs :

• service_name, service_type, service_status
• service_notes
• retail_cost, wholesale_cost
• service_billed, service_taxable
• service_visible_to_customer, service_usage_visible_to_customer
• service_active_date, service_deactivate_date, contract_end_date
• icon, promo_code, site_id

Lecture Seule (Définie Automatiquement) :

Ces champs ne peuvent pas être modifiés directement après création :

• service_id, customer_id, product_id
• service_uuid (généré lors du provisionnement)
• service_provisioned_date
• provisioning_play, provisioning_json_vars
• deprovisioning_play, deprovisioning_json_vars
• bundled_parent
• invoiced (géré par le système de facturation)
• created, last_modified (géré automatiquement)

Provisionnement de Produits en Services

Le processus de provisionnement convertit un Produit (modèle) en un Service (instance spécifique au client) à travers une série d'étapes coordonnées impliquant l'interface Web, l'API et les playbooks Ansible.

Flux de Provisionnement de Haut Niveau

1. Configuration de Pré-provisionnement - Produit créé dans l'API avec configuration de provisionnement, et playbooks Ansible correspondants écrits et testés
2. Sélection de Service - Depuis la Page Client, le personnel ou le client sélectionne "Ajouter un Service"
3. Filtrage des Produits - Produits affichés filtrés en fonction de :
   • Type de client (résidentiel/commercial)
   • Services existants (pour les dépendances d'addon dans relies_on_list)
   • Dates de disponibilité (available_from/available_until)
   • Drapeaux enabled et customer_can_purchase
4. Personnalisation - Option de remplacer les variables de provisionnement (pour des ajustements de prix, des configurations personnalisées, etc.)
5. Sélection d'Inventaire - Si le produit nécessite de l'inventaire (inventory_items_list n'est pas vide), l'utilisateur sélectionne des éléments spécifiques (par exemple, quelle carte SIM, quel numéro de téléphone)
6. Initiation de la Provision - Lorsque le bouton "Provisionner" est cliqué, l'API crée un travail de provisionnement

Flux d'Intégration API et Ansible Détaillé

Lorsqu'un service est provisionné, la séquence suivante se produit :

Étape 1 : Création de Travail de Provisionnement (/routes/service.py)

L'API reçoit la demande de provisionnement et appelle create_provisioning_job() depuis services/provisioning_service.py avec :

• provisioning_play - Nom du playbook Ansible (par exemple, play_psim_only)
• provisioning_json_vars - Chaîne JSON de variables du produit ou remplacées par la demande
• customer_id - ID du client commandant le service
• product_id - ID du produit en cours de provisionnement
• service_id - (Optionnel) ID du service existant pour les addons
• Sélections d'inventaire - Identifiants des éléments d'inventaire sélectionnés

Étape 2 : Assemblage des Variables (services/provisioning_service.py)

Le service de provisionnement fusionne les variables de plusieurs sources dans cet ordre :

1. provisioning_json_vars du Produit (valeurs par défaut de la définition du produit)
2. Paramètres du corps de la demande (peuvent remplacer les valeurs par défaut du produit)
3. Variables ajoutées par le système :
   • access_token - Jeton JWT pour l'authentification API de retour au CRM
   • initiating_user - ID de l'utilisateur qui a déclenché le provisionnement
   • customer_id, product_id, service_id
4. Sélections d'inventaire - Ajoutées sous forme de paires {inventory_type: inventory_id}

Exemple de variables fusionnées :

{
    "customer_id": 123,
    "product_id": 456,
    "service_id": 789,          # Seulement pour les addons
    "SIM Card": 1001,           # Provenant de la sélection d'inventaire
    "Mobile Number": 1002,      # Provenant de la sélection d'inventaire
    "monthly_cost": 30,         # Provenant de provisioning_json_vars
    "data_gb": 50,              # Provenant de provisioning_json_vars
    "access_token": "eyJ...",   # Ajouté par le système pour les rappels API
    "initiating_user": 5        # Ajouté par le système
}

Étape 3 : Création d'Enregistrement de Provision (models.py - Modèle de Provision)

Un enregistrement Provision est créé dans la base de données avec :

• provision_id - Identifiant unique pour le suivi
• provisioning_play - Nom du fichier du playbook
• provisioning_json_vars - Variables fusionnées sous forme de chaîne JSON
• task_count - Nombre de tâches dans le playbook (extrait du YAML)
• provisioning_status - Code de statut (initialement défini sur 1 = en cours, puis mis à jour à 0 = succès, 2 = échec, ou peut rester 1 si toujours en cours)
• product_id, customer_id, service_id - Références contextuelles

Étape 4 : Exécution de Playbook en Arrière-Plan (Provisioners/playbook_runner_v2.py)

L'API lance un thread en arrière-plan qui :

1. Charge le YAML du playbook depuis OmniCRM-API/Provisioners/plays/{playbook_name}.yaml
2. Appelle ansible_runner.run() avec :
   • playbook - Chemin vers le fichier YAML chargé
   • extravars - Toutes les variables fusionnées (passées à Ansible)
   • inventory - Défini sur 'localhost,' (exécution locale)
   • event_handler - Gestionnaire personnalisé pour capturer les événements d'exécution des tâches
3. Surveille l'exécution du playbook en temps réel

Étape 5 : Capture d'Événements et Journalisation (ProvisioningEventHandler)

À mesure que chaque tâche Ansible s'exécute, des événements sont capturés et stockés en tant qu'enregistrements Provision_Event :

• event_name - Nom de la tâche du playbook
• event_number - Numéro de séquence
• provisioning_status - Code de statut indiquant le résultat de la tâche :
  • 0 = Succès - Tâche terminée avec succès
  • 1 = En cours - Tâche en cours d'exécution
  • 2 = Échoué - Échec critique qui arrête le provisionnement
  • 3 = Échoué (ignoré) - La tâche a échoué mais les erreurs ont été ignorées (ignore_errors: true dans le playbook)
• provisioning_result_json - Résultats de la tâche avec des données sensibles masquées

Le gestionnaire d'événements supprime automatiquement les mots de passe, clés, secrets et autres données sensibles des journaux.

Étape 6 : Exécution du Playbook Ansible (Provisioners/plays/*.yaml)

Le playbook Ansible s'exécute localement et effectue généralement ces actions :

a. Récupérer la Définition du Produit - Requête GET à /crm/product/product_id/{{ product_id }} en utilisant {{ access_token }}

b. Récupérer les Informations Client - Requête GET à /crm/customer/customer_id/{{ customer_id }}

c. Traiter les Éléments d'Inventaire (si nécessaire) - Requête GET à /crm/inventory/inventory_id/{{ inventory_id }} pour chaque élément sélectionné afin de récupérer les détails complets (ICCID, MSISDN, numéros de série, etc.)

d. Configurer les Systèmes Externes - Effectuer des appels API à :

• HSS (Serveur d'Abonnés à Domicile) pour le provisionnement des abonnés
• IMS (Système Multimédia IP) pour l'enregistrement vocal
• CGRateS/OCS pour la création de compte, configuration de facturation, plans tarifaires
• Serveurs ENUM pour le mappage des numéros de téléphone
• Équipement réseau (routeurs, commutateurs, etc.)

e. Ajouter des Coûts d'Installation (si applicable) - POST à /crm/transaction/ pour enregistrer des frais uniques

f. Facturer le Client - POST à OCS/CGRateS pour facturer retail_setup_cost si configuré

g. Créer un Compte OCS - POST à OCS/CGRateS pour créer un compte de facturation avec UUID

h. Configurer les Charges Récurrentes - Créer des Actions et des Plans d'Action dans OCS/CGRateS pour les charges récurrentes mensuelles

i. Créer un Enregistrement de Service - PUT/POST à /crm/service/ pour créer l'enregistrement de service dans le CRM :

{
  "customer_id": 123,
  "product_id": 456,
  "service_name": "Mobile SIM - 0412345678",
  "service_uuid": "generated-uuid-for-ocs",
  "service_status": "Active",
  "service_type": "mobile",
  "retail_cost": 30,
  "wholesale_cost": 5,
  "provisioning_play": "play_psim_only",
  "provisioning_json_vars": "{...}"
}

j. Attribuer l'Inventaire - PATCH à /crm/inventory/inventory_id/{{ inventory_id }} pour marquer l'inventaire comme "Attribué" au service

k. Envoyer des Notifications (optionnel) - Email ou SMS au client avec les détails du service

Étape 7 : Achèvement et Mise à Jour du Statut

Lorsque le playbook est terminé :

• Succès : Provision.provisioning_status mis à jour à 0 (Succès)
• Échec Critique : Provision.provisioning_status mis à jour à 2 (Échoué), et un email d'échec envoyé à crm_config.provisioning.failure_list
• Échecs Non-Critiques : Les tâches qui échouent avec ignore_errors: true sont marquées avec le statut 3 (Échoué mais ignoré) et ne stoppent pas le provisionnement

Le service provisionné est maintenant visible dans le CRM et actif pour le client (si le provisionnement a réussi).

Différences Clés : Provisionnement de Produits Autonomes vs Addon vs Bundle

Produits Autonomes (category: standalone) :

• Reçoivent customer_id et product_id
• Nécessitent généralement des éléments d'inventaire (cartes SIM, numéros de téléphone, modems)
• Créent un nouvel enregistrement de service via l'API PUT /crm/service/
• Provisionnent de nouvelles ressources sur des systèmes externes (HSS, OCS, équipement réseau)
• Exemple : Activation d'une nouvelle carte SIM mobile, nouvelle connexion Internet

Produits Addon (category: addon) :

• Reçoivent customer_id, product_id, et service_id (service existant à modifier)
• Nécessitent généralement PAS d'inventaire (ou un inventaire minimal)
• Modifient un service existant ou ajoutent des charges à un compte OCS existant
• Peuvent exécuter des actions sur OCS (ajouter un pack de données, ajouter du crédit, activer une fonctionnalité)
• Ne créent pas de nouveaux enregistrements de service (ou créent des enregistrements de service enfants liés au parent)
• Exemple : Recharge de plan de données mensuel, pack d'itinérance internationale, crédit supplémentaire

Produits Groupés (category: bundle) :

• Semblables aux addons en termes de variables reçues
• Peuvent nécessiter certains éléments d'inventaire (par exemple, modem pour le bundle à domicile)
• Créent plusieurs enregistrements de service liés (Internet + TV + Téléphone)
• Provisionnent plusieurs ressources à travers différents systèmes
• Lient les services ensemble dans le CRM pour une facturation/gestion unifiée
• Exemple : Bundle à domicile (Internet + IPTV + téléphone VoIP)

Exigences du Playbook de Provisionnement

Pour qu'un playbook fonctionne correctement, il doit :

1. Être situé à OmniCRM-API/Provisioners/plays/{playbook_name}.yaml
2. Accepter des variables via extravars d'Ansible (accessibles sous {{ variable_name }})
3. Authentifier les appels API en utilisant l'en-tête Authorization: Bearer {{ access_token }}
4. Gérer les échecs gracieusement en utilisant des blocs rescue et ignore_errors lorsque cela est approprié
5. Créer un enregistrement de service pour les produits autonomes, ou modifier le service existant pour les addons
6. Attribuer l'inventaire si des éléments d'inventaire ont été sélectionnés
7. Retourner des messages d'erreur significatifs via le module fail lorsque des erreurs critiques se produisent

Variables Courantes Disponibles dans les Playbooks

Chaque playbook reçoit ces variables :

• customer_id - Entier, client commandant le service
• product_id - Entier, produit en cours de provisionnement
• service_id - Entier (uniquement pour les addons/groupes), service existant à modifier
• access_token - Chaîne, jeton JWT pour l'authentification API CRM
• initiating_user - Entier, utilisateur qui a déclenché le provisionnement
• Plus tous les identifiants d'éléments d'inventaire : {{ inventory_type }}: inventory_id
• Plus toutes les variables de provisioning_json_vars
• Plus toutes les variables passées dans la demande de provisionnement

Les playbooks peuvent utiliser celles-ci pour :

• Récupérer les détails complets du produit : GET /crm/product/product_id/{{ product_id }}
• Récupérer les détails du client : GET /crm/customer/customer_id/{{ customer_id }}
• Récupérer les détails d'inventaire : GET /crm/inventory/inventory_id/{{ SIM_Card }}
• Créer des transactions : POST /crm/transaction/
• Créer des services : PUT /crm/service/
• Mettre à jour des services : PATCH /crm/service/{{ service_id }}
• Attribuer l'inventaire : PATCH /crm/inventory/inventory_id/{{ inventory_id }}

Exemple : Flux de Playbook d'Addon Simple

Pour un addon de recharge de données mobiles :

1. Le playbook reçoit : customer_id, product_id, service_id, access_token
2. Récupérer les détails du service : GET /crm/service/{{ service_id }} pour obtenir service_uuid
3. Récupérer les détails du produit : GET /crm/product/product_id/{{ product_id }} pour obtenir les prix et la quantité de données
4. Facturer le client dans OCS : POST à CGRateS pour déduire retail_cost du solde
5. Ajouter du crédit de données dans OCS : POST à CGRateS pour ajouter un solde de données avec expiration
6. Enregistrer la transaction dans le CRM : POST /crm/transaction/ avec les détails de la charge
7. Terminer avec succès

L'ensemble du processus est suivi dans les tables Provision et Provision_Event pour le débogage et les audits.

Implication de l'OCS

L'OCS (Système de Facturation en Ligne), mis en œuvre via CGRateS, gère toutes les charges en temps réel et le suivi d'utilisation des services. L'enregistrement de service CRM agit comme un pointeur vers le compte OCS, qui gère :

• Charges récurrentes - Frais mensuels, location de DID, charges d'abonnement
• Facturation basée sur l'utilisation - Appels vocaux par minute, données par Mo, charges par SMS
• Gestion des soldes - Soldes monétaires (crédit prépayé) et soldes unitaires (données Go, minutes de voix, nombre de SMS)
• Conversions de solde - Conversion des soldes monétaires en soldes unitaires (par exemple, dépenser $30 pour obtenir un pack de données de 10 Go)
• État du compte - Actif, suspendu, désactivé en fonction des limites de crédit et des seuils

L'enregistrement de service CRM contient des métadonnées et des configurations (client, produit, tarification, visibilité), tandis que l'OCS contient l'état de facturation en direct (soldes, utilisation, charges).

Récupération de l'Utilisation et des Soldes de Service

Les informations d'utilisation du service sont récupérées à partir de OCS/CGRateS et affichées aux clients et au personnel en temps réel.

Comment l'Utilisation est Récupérée

Lorsqu'une utilisation de service est demandée (via l'UI ou l'API), le flux suivant se produit :

1. Demande API - Le frontend appelle GET /crm/service/{service_id} ou consulte les détails du service dans l'UI

2. Recherche de Service - L'API récupère l'enregistrement de service dans la base de données, extrait service_uuid

3. Appels API CGRateS - Le module cgrates_service.py effectue deux appels à CGRateS :

   a. Get_Balance(service_uuid) - Récupère le solde du compte avec BalanceMap

   • Retourne des soldes organisés par type : DONNÉES, VOIX, SMS, MONÉTAIRE, DONNÉES_DONGLE
   • Chaque solde comprend : ID, Valeur, Date d'Expiration, Poids, Identifiants de Destination
   • Le système ajoute des champs lisibles par l'homme : custom_Name_hr, custom_Expiration, custom_Description_String b. Get_ActionPlans(service_uuid) - Récupère les plans d'action de renouvellement automatique actifs (couverts dans la section suivante)

4. Fusion de Réponse - Les données de CGRateS sont fusionnées dans la réponse de service :

   {
     "service_id": 123,
     "service_name": "Mobile Service",
     "service_uuid": "abc-123-def",
     "cgrates": {
       "BalanceMap": {
         "DATA": [{
           "ID": "DATA_10GB",
           "Value": 5368709120,
           "ExpirationDate": "2025-02-01T00:00:00Z",
           "custom_Name_hr": "10GB Data Pack",
           "custom_Expiration": "Feb 1, 2025",
           "custom_Description_String": "5 GB remaining"
         }],
         "VOICE": [{
           "ID": "VOICE_UNLIMITED",
           "Value": 999999999,
           "custom_Name_hr": "Unlimited Calls",
           "custom_Description_String": "Unlimited minutes"
         }],
         "MONETARY": [{
           "ID": "PREPAID_CREDIT",
           "Value": 25.50,
           "custom_Description_String": "$25.50 credit"
         }]
       },
       "ActionPlans": [...]
     }
   }

5. Affichage UI - Les composants frontend affichent les données d'utilisation :

   • ServiceUsage.js - Composant principal d'affichage d'utilisation avec actualisation automatique toutes les 3 secondes
   • UsageCard.js - Cartes de résumé pour chaque type de solde
   • UsageProgress.js - Barres de progression montrant le pourcentage utilisé/restant
   • Les soldes sont codés par couleur et formatés pour la lisibilité

Structure des Données d'Utilisation

Chaque solde dans le BalanceMap contient :

Champs Natifs CGRateS :

• ID - Identifiant unique pour le solde (par exemple, "DATA_10GB_2025_01")
• Value - Montant du solde :
  • Pour DONNÉES : octets (5368709120 = 5 Go)
  • Pour VOIX : secondes (3600 = 1 heure)
  • Pour SMS : compte (100 = 100 messages)
  • Pour MONÉTAIRE : unités monétaires (25.50 = $25.50)
• ExpirationDate - Horodatage ISO 8601 lorsque le solde expire
• Weight - Priorité pour la consommation de solde (poids plus élevé consommé en premier)
• DestinationIDs - Destinations auxquelles ce solde s'applique (par exemple, ["AU", "INTERNATIONAL"])

Champs Lisibles par l'Homme (ajoutés par le CRM) :

• custom_Name_hr - Nom lisible par l'homme extrait de l'ID
• custom_Expiration - Date d'expiration formatée (par exemple, "15 janv. 2025" ou "dans 11 jours")
• custom_Description_String - Description de solde lisible par l'homme :
  • DONNÉES : "5 Go restants" ou "10 Go au total"
  • VOIX : "60 minutes restantes" ou "Illimité"
  • SMS : "50 SMS restants"
  • MONÉTAIRE : "$25.50 de crédit"

Contrôle de Visibilité de l'Utilisation

La visibilité de l'utilisation du service est contrôlée par deux champs :

• service_visible_to_customer - Si faux, le service est entièrement masqué du portail d'auto-assistance du client
• service_usage_visible_to_customer - Si faux, le service est visible mais les détails d'utilisation/solde sont masqués (le client peut voir qu'il a le service, mais pas combien il a utilisé)

Cela permet aux opérateurs de :

• Masquer les services internes/test aux clients
• Montrer que le service existe sans révéler l'utilisation (utile pour les plans illimités ou les services sensibles)
• Affichage d'utilisation entièrement transparent (par défaut)

Mises à Jour d'Utilisation en Temps Réel

L'interface Web actualise automatiquement les données d'utilisation :

• Intervalle : Toutes les 3 secondes (configurable dans le composant ServiceUsage)
• Méthode : Interroge GET /crm/service/{service_id} qui récupère des données en direct de CGRateS
• Efficacité : Seules les vues de service actives se rafraîchissent ; les vues de liste utilisent des données mises en cache

Cela garantit que les clients et le personnel voient des mises à jour de solde presque en temps réel à mesure que l'utilisation se produit.

Charges Récurrentes / Renouvellement Automatique

Les charges récurrentes, telles qu'une Charge de Service Mensuelle, ou une Charge par DID, sont d'abord créées en tant qu'Actions à l'intérieur de l'OCS et prennent le format Action_ServiceUUID_ServiceName_WhatitDoes.

Pour par exemple un service GPON à $60 par mois qui inclut 1 To d'utilisation, l'Action ressemblerait à ceci :

Action_kj49-adsf-1234-9742_60_GPON_1TB_MonthlyExpiry

1. Réinitialiser le Solde Monétaire à $0
2. Envoyer un POST HTTP à /simple_provision sur le CRM pour provisionner quelque chose
3. Ajouter un Crédit pour 1 To d'Utilisation expirant dans 1 mois

Si nous voulons que le MRC soit récurrent (nous le faisons), nous créerions un ActionPlan nommé ActionPlan_{{ service_uuid }}_Monthly_Charge qui aurait le temps défini sur mensuel pour se déclencher chaque mois, et assigner le ActionPlan au compte.

Nous pouvons définir en fonction du paramètre Année / Mois / Jours une date d'expiration pour quand le MRC s'arrêtera également, par exemple pour un service fixe de 12 mois qui s'arrête après ce point.

Parce que les Actions et les ActionPlans sont tous deux uniques au service, ils ne partagent rien avec d'autres services.

Cela signifie que nous pouvons les provisionner avec des valeurs ajustées, et cela n'impactera aucun autre service.

Addons & Options Supplémentaires

Les Addons / Options Supplémentaires tels que l'achat de données supplémentaires, de packs d'itinérance, de minutes internationales, etc., sont gérés de la même manière. Une Action est créée pour faire ce qui est nécessaire, comme facturer une valeur monétaire et ensuite accorder un solde unitaire avec une expiration définie.

Plutôt que d'utiliser des ActionPlans pour ajouter automatiquement cela à se reproduire sur le compte, nous déclenchons simplement ExecuteAction pour l'Action que nous venons de créer une fois depuis Ansible.

Ajout de Soldes Monétaires Prépayés

Pour les soldes monétaires prépayés, tels qu'un plan PAYG de $10, cela est ajouté en tant que solde monétaire, mais avec une priorité plus élevée.

La limite de crédit sur ces services pour le solde par défaut serait $0.

Limites de Crédit / Prévention des Dépenses Excessives

Les ThresholdS sont utilisés sur chaque compte pour définir la dépense maximale pour une période donnée.

Pour les clients PAYG / Prépayés, cela est $0.

Interaction avec OCS via CRM

Pour chaque Service, vous pouvez voir les Balances et ActionPlans, Actions et ThresholdS de l'OCS depuis l'API CRM.

Les ActionPlans peuvent être supprimés si nécessaire depuis l'API CRM, actionnés via des Playbooks Ansible. Les ActionPlans peuvent être ajoutés si nécessaire, depuis le CRM, en ajoutant un Addon/Service et actionnés via des Playbooks Ansible.

Les comptes OCS peuvent être désactivés, ce qui arrêtera l'exécution des ActionPlans et empêchera les services d'être consommés.

Pour les Limites de Crédit, une valeur de ThresholdS est définie selon la politique pour le produit.

Visualisation et Gestion des ActionPlans dans le CRM

Les ActionPlans (configurations de renouvellement automatique) sont affichés et gérés à travers l'interface CRM, permettant au personnel et aux clients de voir les renouvellements automatiques à venir et de les gérer.

Comment les ActionPlans sont Récupérés et Affichés

Lors de la visualisation d'un service dans le CRM, les ActionPlans sont automatiquement récupérés et affichés :

1. Appel API - Lorsque GET /crm/service/{service_id} est appelé, l'API :

   • Récupère l'enregistrement de service dans la base de données
   • Extrait le service_uuid (identifiant de compte OCS)
   • Appelle get_cgrates_action_plans_by_service_uuid(service_uuid) depuis cgrates_service.py
   • Cela appelle en interne ocs.Get_ActionPlans(service_uuid) pour récupérer les ActionPlans de CGRateS

2. Structure de Données d'ActionPlan - Chaque ActionPlan retourné contient :

   {
       "ActionPlanId": "ServiceID_abc-123-def__ProductID_456__...",
       "PlanName": "Monthly_Renewal_Plan",
       "NextExecTime": "2025-02-01T00:00:00Z",
       "custom_NextExecTime_hr": "in 11 days",
       "ActionPlanId_split_dict": {
           "ServiceID": "abc-123-def",
           "ProductID": 456,
           "CustomerID": 789,
           ...
       }
   }

   • ActionPlanId - Identifiant unique contenant des informations encodées sur le service/produit/client
   • PlanName - Nom du plan d'action (typiquement le nom du playbook de renouvellement)
   • NextExecTime - Horodatage ISO lorsque le plan d'action sera exécuté
   • custom_NextExecTime_hr - Temps lisible par l'homme jusqu'à l'exécution (par exemple, "dans 11 jours", "demain", "1 févr. 2025")
   • ActionPlanId_split_dict - Dictionnaire avec les composants analysés de l'ActionPlanId

3. Affichage UI - Les ActionPlans sont affichés dans le composant ActionPlansTable :

   Colonnes du Tableau :

   • Nom du Produit - Récupéré en consultant ProductID depuis l'ActionPlanId
   • Coût - Affiche retail_cost de la définition du produit
   • Date de Renouvellement - Affiche custom_NextExecTime_hr (lisible par l'homme)
   • Actions - Deux boutons :
     • Renouveler Maintenant - Provisionner immédiatement l'addon/renouvellement (contourne l'attente de l'exécution programmée)
     • Supprimer le Renouvellement Automatique - Annule le renouvellement automatique

   Lorsque Aucun ActionPlan n'Existe :

   • Le tableau affiche le message : "Aucun renouvellement automatique activé pour ce service"
   • Le client peut ajouter des addons renouvelables automatiquement pour activer le renouvellement automatique

Gestion des ActionPlans

Le personnel et les clients peuvent gérer les ActionPlans via l'interface utilisateur :

Suppression d'un ActionPlan (Annulation du Renouvellement Automatique) :

1. Cliquez sur le bouton "Supprimer le Renou