Editing transformations

Folder structure

Les transformations d'une application de processus consistent en un projet dbt . Vous trouverez ci-dessous une description du contenu d'un dossier de projet dbt .

Dossier/Fichier	Contient
dbt_packages\	le package pm_utils et ses macros.
logs\	journaux créés lors de l’exécution de dbt.
macros\	macros personnalisées.
models\	.sql qui définissent les transformations.
models\schema\	.yml qui définissent les tests sur les données.
seed	.csv avec les paramètres de configuration.
dbt_project.yml	les paramètres du projet dbt.

Voir illustration ci-dessous.

Transformations de données

Les transformations de données sont définies dans des fichiers .sql dans le répertoire models\ . Les transformations de données sont organisées dans un ensemble standard de sous-répertoires :

• 1_input,
• 2_entities,
• 3_events,
• 4_event_logs,
• 5_business_logic.

Voir Structure des transformations.

Les fichiers .sql sont écrits en Jinja SQL, ce qui vous permet d'insérer des instructions Jinja dans des requêtes SQL simples. Lorsque dbt exécute tous les .sql fichiers, chaque fichier .sql génère une nouvelle vue ou une nouvelle table dans la base de données.

En règle générale, les fichiers .sql ont la structure suivante :

1. Instruction With: une ou plusieurs instructions with pour inclure les sous-tables requises.

   • {{ ref(‘My_table) }} fait référence à une table définie par un autre fichier .sql fichier.
   • {{ source(var("schema_sources"), 'My_table') }} fait référence à une table d'entrée.
2. Requête principale: la requête qui définit la nouvelle table.
3. Requête finale: une requête telle que Select * from table est généralement utilisée à la fin. Cela facilite la réalisation de sous-sélections lors du débogage.

   

Pour plus de conseils sur l'écriture efficace des transformations, consultez Conseils pour l'écriture de SQL

Adding source tables

Pour ajouter une nouvelle table source au projet dbt , elle doit être répertoriée dans models\schema\sources.yml . De cette façon, d'autres modèles peuvent s'y référer en utilisant {{ source(var("schema_sources"), 'My_table_raw') }} . Voir l’illustration ci-dessous pour un exemple.

Important : chaque nouvelle table source doit être répertoriée dans sources.yml .

Remarque :

Le suffixe _raw est ajouté aux noms de table des tables source lors du chargement des données. Par exemple, une table appelée ma_table doit être appelée ma_table_raw.

Pour plus d'informations, consultez la documentation officielle de dbt sur Sources.

Data output

Les transformations de données doivent générer le modèle de données requis par l'application correspondante ; chaque table et chaque champ attendus doivent être présents.

En pratique, cela signifie que les tables du models\5_business_logic ne doivent pas être supprimées. De plus, les champs de sortie des requêtes correspondantes ne doivent pas être supprimés.

Si vous souhaitez ajouter de nouveaux champs à votre application de processus, vous pouvez utiliser les champs personnalisés disponibles pour l'application de processus. Mappez les champs des transformations aux champs personnalisés pour les rendre disponibles dans la sortie. Assurez-vous que les champs personnalisés sont nommés dans la sortie comme décrit dans le modèle de données de l'application de processus.

Astuce :

Vous pouvez utiliser les commandes dbt docs pour générer un site de documentation pour votre projet dbt et l'ouvrir dans votre navigateur par défaut. Le site de documentation contient également un graphique de lignage qui fournit un diagramme entité-relation avec une représentation graphique du lien entre chaque table de données de votre projet.

Pour des informations détaillées, consultez la documentation officielle de dbt sur dbt docs.

Macros

Les macros facilitent la réutilisation des constructions SQL courantes. Pour plus d'informations, consultez la documentation officielle de dbt sur les macros Jinja.

pm_utils

Le paquet pm-utils contient un ensemble de macros qui sont généralement utilisées dans les transformations Process Mining. Pour plus d'informations sur les macros pm_utils , consultez ProcessMining-pm-utils.

Vous trouverez ci-dessous un exemple de code Jinja appelant la macro pm_utils.optional() .

Graines

Les valeurs sont des fichiers csv utilisés pour ajouter des tables de données à vos transformations. Pour des informations détaillées, consultez la documentation officielle de dbt sur les labels jinja.

Dans Process Mining, cela est généralement utilisé pour faciliter la configuration des mappages dans vos transformations.

Après la modification des fichiers de départ, ces fichiers ne sont pas automatiquement mis à jour immédiatement dans la base de données. Pour indiquer à dbt de charger le nouveau contenu du fichier d'origine dans la base de données, exécutez soit

• dbt seed - qui ne mettra à jour que les tables des fichiers d'origine, ou
• dbt build - qui exécutera également tous les modèles et tests.
  Remarque : si le fichier d'origine ne contenait aucun enregistrement de données au départ, les types de données dans la base de données n'avaient peut-être pas été définis correctement. Pour résoudre ce problème, appelez run dbt seed --full-refresh . Cela mettra également à jour l'ensemble de colonnes dans la base de données.

Activity configuration

Le fichier activity_configuration.csv est utilisé pour définir des champs supplémentaires liés aux activités. activity_order est utilisé comme condition de départage lorsque deux événements se produisent avec le même horodatage. Voir l’illustration ci-dessous pour un exemple.

Tests

Le dossier models\schema\ contient un ensemble de fichiers .yml qui définissent les tests. Ceux-ci valident la structure et le contenu des données attendues. Pour plus d'informations, consultez la documentation officielle de dbt sur les tests.

Lorsque les transformations sont exécutées dans Process Mining, seuls les tests dans sources.yml sont exécutés à chaque ingestion de données. Cela permet de vérifier si les données d'entrée sont correctement formatées.

Remarque : lorsque vous modifiez des transformations, veillez à mettre à jour les tests en conséquence. Les tests peuvent être supprimés si vous le souhaitez.

Métriques de temps de traitement personnalisées

Introduction

Grâce à la personnalisation des transformations de données et à la modification du tableau de bord, vous pouvez créer et utiliser des mesures de temps de traitement personnalisées. Les temps de traitement sont les délais entre deux activités A et B. Vous trouverez ci-dessous une description des étapes que vous devez effectuer pour créer une mesure de temps de traitement personnalisée lors de la modification des transformations et comment activer la mesure de temps de traitement dans les tableaux de bord de l'application de processus.

Création d'une mesure de temps de débit personnalisée avec modification des transformations

Vous devez d'abord calculer le délai d'exécution, puis le rendre disponible en tant que champ Cas .

Calcul du temps d'exécution

Par cas, vous pouvez calculer les délais de traitement entre l'activité A et l'activité B. Étant donné que les activités peuvent se produire plusieurs fois par cas, vous devez déterminer si vous prenez la première ou la dernière occurrence d’une activité.

1. Créez un modèle supplémentaire basé sur le journal des événements pour calculer les délais de traitement souhaités. Par exemple, Cases_with_throughput_times.

2. Dans ce modèle, créez des tables de prétraitement dans lesquelles vous définissez les fins d'événement que vous souhaitez utiliser pour les calculs. Par table, vous avez besoin de l' ID de caset de la fin d'événement d'une activité. Vous trouverez ci-dessous un exemple de sélection de la dernière occurrence de l'activité A pour un incident.

   Event_end_activity_A as (
       select
           Event_log."Case_ID",
           max(Event_log."Event_end") as "Event_end_activity_A"
       from Event_log
       where Event_log."Activity" = 'Activity A'
       group by Event_log."Case_ID")

   Remarque :

   Dans cet exemple, si vous souhaitez sélectionner la première occurrence de l'activité, remplacez max par min.

3. Définissez la table de temps de débit en joignant les tables de pré-traitement au journal des événements et en calculant le temps de débit réel.

   Astuce :

   Vous pouvez utiliser la fonction datediff fournie dans le package pm-utils pour calculer la différence de temps entre deux fins d'événement.

   Le temps de débit doit être calculé en millisecondes pour les instances où l' activité A précède l' activité B. Les millisecondes sont l'unité de temps utilisée pour définir les durées dans le modèle d'application. Étant donné que les délais de traitement sont déjà regroupés par incident dans les tables de prétraitement, vous pouvez sélectionner n'importe quel enregistrement. Dans l’exemple ci-dessus, l’agrégation min est utilisée. Le tableau des délais de traitement, en sélectionnant le délai de traitement et un ID de cas, peut être défini comme affiché ci-dessous.

   Cases_with_throughput_times as (
       select
           Event_log."Case_ID",
           case
               when min(Event_end_activity_A."Event_end_activity_A") <= min(Event_end_activity_B."Event_end_activity_B")
                   then {{ pm_utils.datediff('millisecond',
                   'min(Event_end_activity_A."Event_end_activity_A")',
                   'min(Event_end_activity_B."Event_end_activity_B")') }}
           end as "Throughput_time_activity_A_to_activity_B"
       from Event_log
       left join Event_end_activity_A
           on Event_log."Case_ID" = Event_end_activity_A."Case_ID"
       left join Event_end_activity_B
           on Event_log."Case_ID" = Event_end_activity_B."Case_ID"
       group by Event_log."Case_ID)"

Calcul du délai d'exécution en jours hors week-ends

Vous pouvez utiliser la fonction date_from_timestamp fournie dans le package pm-utils pour calculer le nombre de jours entre deux activités. En outre, la fonction diff_weekdays permet de filtrer les jours de week-end.

Consultez l'exemple de code ci-dessous pour savoir comment calculer le nombre de jours de la semaine entre l' activité A et l' activité B.

with Event_log as (
    select * from {{ ref('Event_log') }}
),

Activity_A as (
    select
        Event_log."Case_ID",
        min({{ pm_utils.date_from_timestamp('Event_log."Event_end"') }}) as "Date_activity_A"
    from Event_log
    where Event_log."Activity" = 'Receive invoice'
    group by Event_log."Case_ID"
),

Activity_B as (
    select
        Event_log."Case_ID",
        min({{ pm_utils.date_from_timestamp('Event_log."Event_end"') }}) as "Date_activity_B"
    from Event_log
    where Event_log."Activity" = 'Pay invoice'
    group by Event_log."Case_ID"
),

Total_days_minus_weekends as (
    select
        Activity_A."Case_ID",
        Activity_A."Date_activity_A",
        Activity_B."Date_activity_B",
        {{ pm_utils.diff_weekdays('Activity_A."Date_activity_A"', 'Activity_B."Date_activity_B"') }}
    -- Only compute for cases where both dates are known.
    from Activity_A
    inner join Activity_B
        on Activity_A."Case_ID" = Activity_B."Case_ID"
)

select * from Total_days_minus_weekends

Calcul du délai d'exécution en jours hors jours fériés

Suivez les étapes ci-dessous pour calculer le délai d'exécution en jours entre l' activité A et l' activité B hors week-ends et jours fériés.

1. Créez un fichier Holidays.csv pour définir les jours qui doivent être comptés comme jours fériés. Le fichier doit contenir au moins un enregistrement pour chaque jour férié. Utilisez le format suivant :

Jour férié	Date	Jour de la semaine
Jour du nouvel an	2024-01-01	Oui (Yes)
Paques	2024-03-31	Non (No)
..	..	..

Les enregistrements du fichier Holidays.csv sont utilisés pour compter le nombre de jours qui doivent être exclus d'une plage de dates.

2. Chargez le fichier Holidays.csv en tant que fichier de référence dans le projet dbt . Pour des informations détaillées, consultez la documentation officielle de dbt sur les labels jinja.

3. Calculez le délai d'exécution en jours hors week-ends à l'aide des fonctions date_from_timestamp et diff_weekdays fournies dans le package pm-utils tel que décrit ci-dessus dans Calcul du délai d'exécution en jours hors week-ends.

4. Calculez le nombre d'enregistrements stockés dans le fichier de vacances .csv qui se situent dans la plage de dates donnée pour chaque incident. Voir l'exemple de code ci-dessous.

Holidays_count as (
    select
        Total_days_minus_weekends."Case_ID",
        count(Holidays."Date") as "Number_of_holidays"
    from Total_days_minus_weekends
    left join Holidays
        on Holidays."Date" between Total_days_minus_weekends."Date_activity_A" and Total_days_minus_weekends."Date_activity_B"
    where Holidays."Weekday" = 'Yes'
    group by Total_days_minus_weekends."Case_ID"
)

Remarque :

Dans l'exemple ci-dessus, le filtre Weekday = 'Yes' est utilisé pour ne pas soustraire les jours fériés lorsque ceux-ci sont un samedi ou un dimanche. Ceci est déjà pris en charge dans la fonction diff_weekday .

5. Soustrayez le nombre calculé de vacances du nombre total de jours calculés pour chaque cas. Voir l'exemple de code ci-dessous.

Total_days_minus_weekends_and_holidays as (
    select
        Total_days_minus_weekends."Case_ID",
        Total_days_minus_weekends."Number_of_days" - Holidays_count."Number_of_holidays" as "Number_of_days_between_dates"
    from Total_days_minus_weekends
    inner join Holidays_count
        on Total_days_minus_weekends."Case_ID" = Holidays_count."Case_ID"
)

Rendre le délai d’exécution disponible en tant que champ de cas

Une fois la table de temps de débit créée, cette table doit être jointe à la table Cas pour ajouter les données de temps de débit supplémentaires en tant qu'informations de cas. Pour que le nouveau champ de délai de traitement soit disponible dans les tableaux de bord, il est nécessaire de convertir le nouveau champ de délai de traitement en l'un des champs de durée de cas personnalisés.

Remplacez l'une des lignes de durée d'incident personnalisées dans le tableau Incidents ( Recases ) qui ressemble à ceci :

{{ pm_utils.optional(ref('Cases_base'), '"custom_case_duration_1"', 'integer') }} as "custom_case_duration_1",

avec le temps de débit nouvellement créé :

Cases_with_throughput_times."Throughput_time_activity_A_to_activity_B" as "custom_case_duration_1",

Les mises à jour des transformations de la mesure de temps de débit personnalisée sont maintenant effectuées et peuvent être importées dans le modèle d'application.

Activation de la mesure du temps de débit dans les tableaux de bord de l'application de processus

Lorsque vous avez créé un délai d'exécution personnalisé dans vos transformations, il est disponible dans votre modèle d'application en tant que propriété de cas sous son alias. Vous pouvez personnaliser votre application de processus pour créer une métrique de délai d'exécution basée sur le délai d'exécution personnalisé que vous avez créé dans les transformations.

Remarque :

Par défaut, un nouveau champ de durée personnalisé est ajouté en tant que champ de type numérique(numerical). Assurez-vous de modifier le champ et de changer le Type du nouveau champ en durée. Voir également Gestionnaire de données.

• Accédez au Gestionnaire de données (Data Manager) et créez une nouvelle mesure.
• Sélectionnez le champ de durée personnalisé à utiliser pour le temps de débit, puis sélectionnez Moyenne ou toute autre agrégation souhaitée. Vous pouvez également renommer le champ de durée de l'incident personnalisé avec le nom souhaité dans le Gestionnaire de données.
• Modifiez l'application et placez la nouvelle mesure sur les graphiques où vous souhaitez la rendre disponible pour les utilisateurs professionnels.
• Publiez les tableaux de bord pour que la métrique du délai d'exécution y soit disponible.

Remarque :

Dans les modèles d'application Purchase-to-Pay et Order-to-Cash , un calcul du temps de traitement est déjà disponible dans Purchase_order_items_with_throughput_times et Sales_order_items_with_throughput_times, respectivement. Des délais de traitement personnalisés peuvent y être ajoutés, puis être disponibles en tant que durée personnalisée sur Purchase_order_items ou Sales_order_items.

SQL differences between Snowflake and SQL Server

SQL Server vs. Snowflake

Dans un environnement de développement local, les transformations sont exécutées sur SQL Server, tandis que Snowflake est utilisé dans Process Mining Automation Suite. Bien que la plupart des instructions SQL fonctionnent à la fois sur SQL Server et Snowflake, il peut exister de légères différences dans la syntaxe, ce qui peut entraîner des résultats de renvoi différents.

Pour écrire des instructions SQL qui fonctionnent sur les deux systèmes de base de données :

• Écrivez les noms de champ entre guillemets doubles, par exemple Table."Field" .
• Empêcher l'utilisation de fonctions SQL différentes dans Snowflake et SQL Server, par exemple string_agg() et listagg() .
  Le package pm_utils est livré avec un ensemble de fonctions qui fonctionnent sur les deux types de bases de données, voir Bases de données multiples. Par exemple, au lieu d'utiliser string_agg() ou listagg() , pm_utils.string_agg() entraînera le même comportement pour les deux bases de données. Si pm_utils ne contient pas la fonction souhaitée, une instruction Jinja doit être créée pour s'assurer que la bonne fonction est appelée sur chaque base de données.

Concaténation de string

Pour combiner en chaînes, utilisez la fonction pm_utils.concat() . Cela produira les mêmes résultats pour SQL Server et Snowflake.

Exemple : pm_utils.concat("This is a nice string", null) = "This is a nice string" La concaténation de chaînes ne doit pas être effectuée avec des opérateurs tels que + ou || , car ils sont différents pour les deux bases de données (Snowflake utilise || et SQL Server utilise + ). De plus, la fonction standard concat() a un comportement différent sur les deux systèmes :

SQL Server	Snowflake
Les valeurs null seront ignorées et traitées comme une chaîne vide.	Les valeurs null donneront au résultat entier la valeur null .

Tri

Le tri est géré différemment dans Snowflake et dans SQL Server.

Exemple : ... order by "Attribute_1" desc, "Attribute_2" ...

Valeurs nulles

SQL Server	Snowflake
null sera trié par défaut en premier (croissant)	null sera trié par défaut en dernier (croissant)

Handling capital letters

SQL Server	Snowflake
les majuscules sont triées comme prévu (AaBbCc)	trie d'abord par majuscules, puis par lettres non majuscules (ABCabc)

En tirets

Exemple : -Accountant-

SQL Server	Snowflake
les tirets sont ignorés dans le tri (de sorte que « -Accountant- » soit traité de la même manière que « Accountant »)	les tirets seront triés en haut

Gestion des espaces

Lorsque vous effectuez un regroupement par valeurs « A » et « A », cela est considéré comme une seule valeur dans SQL Server, mais comme deux valeurs différentes dans Snowflake. Par conséquent, le rognage est conseillé si vos données peuvent causer ce problème.

Sensible à la casse

Par défaut, SQL Server ne respecte pas la casse tandis que Snowflake est sensible à la casse. Cela signifie que Table."Field" = "Some_value" et Table."Field" = "SOME_VALUE" renverront le même ensemble de résultats dans SQL Server, mais potentiellement deux ensembles de résultats différents dans Snowflake.

Il est conseillé de modifier le comportement de votre base de données SQL Server locale pour qu'il corresponde au comportement de Snowflakes, afin d'éviter tout problème. Cela peut être accompli en définissant le classement de la base de données sur une valeur sensible à la casse.

Configuration settings for loading input data

Settings.json

The settings.json file contains settings related to loading input data. These settings are temporary and should be used to switch existing process apps (created before March 2023) to the new data loading behavior. You should not change the settings.json file for new process apps.

Lorsque vous créez une nouvelle application de processus, assurez-vous toujours que les données d'entrée sont au format requis pour le modèle d'application que vous utilisez pour créer une nouvelle application. Voir Modèles d'applications.

Important :

Les nouvelles applications de processus s'appliqueront par défaut au nouveau modèle de données. Les applications de processus existantes continueront de fonctionner dans Process Mining 2023.4 et Process Mining 2023.10. Basculez les paramètres de chargement de données de vos applications de processus avant Process Mining 2024.4, pour vous assurer que le téléchargement des données continue de fonctionner correctement. Les paramètres AddRawTablePostfix et StripSpecialCharacters sont temporaires et seront supprimés dans Process Mining 2024.4. À partir de ce moment, toutes les applications de processus fonctionneront comme si ces paramètres étaient définis sur false.

Paramètre	Format	Description
AjouterSuffixeTableBrut (AddRawTablePostfix)	boolean	Pour ajouter un suffixe _raw à vos tables source lors de l'utilisation de téléchargements de fichiers via l'option Télécharger les données ( Upload data ). Par exemple, si le fichier que vous téléchargez s'appelle Event_log.csv , il devient Event_log_raw.csv si ce paramètre est défini sur true.
RéduireCaractèresSpéciaux (StripSpecialCharacters)	boolean	Pour supprimer les caractères spéciaux et remplacer les espaces par des traits de soulignement dans les noms de table et/ou les noms de champ. Par exemple, un champ appelé Event+end se transforme en Eventend.

Utilisation des applications de processus existantes avec les nouveaux paramètres de modèle de données

Suivez ces étapes pour utiliser vos applications de processus existantes avec les nouveaux paramètres de modèle de données.

1. Download the settings.json.zip and unzip the file.

2. Exportez les transformations de votre application de processus. Voir Modification des transformations de données dans un environnement local.

3. Add the settings.json file (if not already present) to transformations.

4. Assurez-vous que AddRawTablePostfix et StripSpecialCharacters sont tous deux définis sur false.

5. Modifiez vos fichiers d'entrée, ou vos transformations, de sorte que les noms de fichiers correspondent exactement. Par exemple, si vos transformations d'entrée attendent journal_événement_raw , votre fichier csv doit également s'appeler journal_événement_raw.csv.

6. Si vous utilisez des caractères spéciaux dans les noms de table ou les noms de champ (par exemple, « », « ( » ou « ? »), assurez-vous que les transformations d’entrée utilisent le même nom. Par exemple, un champ Catégorie d'activité doit être appelé Catégorie d'activité dans vos requêtes et non Catégorie_Activité.

7. Importez des transformations et ingérez de nouvelles données.

Les transformations seront à nouveau exécutées dans la plate-forme et les tables source seront modifiées en conséquence.

Projets dbt

Les transformations de données sont utilisées pour transformer les données d'entrée en données adaptées à Process Mining. Les transformations dans Process Mining sont écrites en tant que projets dbt .

Cette page donne une introduction à dbt. Pour plus d'informations, consultez la documentation officielle de dbt.

pm-utils package

Les modèles d'application Process Mining sont fournis avec un package dbt appelé pm_utils. Ce package pm-utils contient des fonctions utilitaires et des macros pour les projets dbt Process Mining. Pour plus d'informations sur les pm_utils , consultez ProcessMining-pm-utils.

Mise à jour de la version pm-utils utilisée pour votre modèle d'application

UiPath® améliore constamment le package pm-utils en ajoutant de nouvelles fonctions.

Lorsqu'une nouvelle version du paquet pm-utils est publiée, il est conseillé de mettre à jour la version utilisée dans vos transformations, pour vous assurer que vous utilisez les dernières fonctions et macros du paquet pm-utils .

Vous trouverez le numéro de version de la dernière version du package pm-utils dans le panneau Versions ( Releases ) du ProcessMining-pm-utils.

Suivez ces étapes pour mettre à jour la version pm-utils dans vos transformations.

1. Téléchargez le code source (zip) à partir de la version pm-utils.
2. Extrayez le fichier zip et renommez le dossier en pm_utils.

3. Exportez les transformations à partir de l'éditeur de transformations de données intégré et extrayez les fichiers.

4. Remplacez le dossier pm_utils des transformations exportées par le nouveau dossier pm_utils .

5. Compressez à nouveau le contenu des transformations et importez-les dans l' éditeur de transformations de données .