Editing transformations

Folder structure

As transformações de um aplicativo de processo consistem em um projeto dbt . Abaixo está uma descrição do conteúdo de uma pasta de projeto dbt .

Pasta/Arquivo	Contém
dbt_packages\	o pacote pm_utils e suas macros.
logs\	logs criados ao executar dbt.
macros\	macros personalizadas.
models\	.sql arquivos que definem as transformações.
models\schema\	.yml arquivos que definem testes nos dados.
seed	.csv arquivos com definições de configuração.
dbt_project.yml	as configurações do projeto dbt.

Veja o exemplo abaixo.

Transformações de dados

As transformações de dados são definidas em arquivos .sql no diretório models\ . As transformações de dados são organizadas em um conjunto padrão de subdiretórios:

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

Consulte Estrutura das transformações.

Os arquivos .sql são escritos em SQL Jinja, o que permite inserir instruções Jinja dentro de consultas SQL simples. Quando dbt executa todos os arquivos .sql , cada arquivo .sql resulta em uma nova exibição ou tabela no banco de dados.

Normalmente, os arquivos .sql têm a seguinte estrutura:

1. Instruções With: Uma ou mais instruções with para incluir as subtabelas necessárias.

   • {{ ref(‘My_table) }} refere-se à tabela definida por outro .sql arquivo.
   • {{ source(var("schema_sources"), 'My_table') }} refere-se a uma tabela de entrada.
2. Consulta principal: a consulta que define a nova tabela.
3. Consulta final: Normalmente, uma consulta como Select * from table é usada no final. Isso facilita fazer subseleções durante a depuração.

   

Para obter mais dicas sobre como escrever transformações de forma eficaz, consulte Dicas para escrever SQL

Adding source tables

Para adicionar uma nova tabela de origem ao projeto dbt , ela deve estar listada em models\schema\sources.yml. Dessa forma, outros modelos podem se referir a ele usando {{ source(var("schema_sources"), 'My_table_raw') }}. Veja a ilustração abaixo para um exemplo.

Importante: Cada nova tabela de origem deve ser listada em sources.yml.

Observação:

O sufixo _raw é adicionado aos nomes das tabelas das tabelas de origem ao carregar dados. Por exemplo, uma tabela chamada my_table deve ser referida como my_table_raw.

Para obter informações mais detalhadas, consulte a documentação oficial do dbt em Sources.

Data output

As transformações de dados devem gerar o modelo de dados exigido pelo aplicativo correspondente; cada tabela e campo esperados devem estar presentes.

Na prática, isso significa que as tabelas no models\5_business_logic não devem ser excluídas. Além disso, os campos de saída nas consultas correspondentes não devem ser removidos.

Se você deseja adicionar novos campos ao seu aplicativo de processo, pode usar os campos personalizados que estão disponíveis para o aplicativo de processo. Mapeie os campos nas transformações para os campos personalizados para disponibilizá-los na saída. Certifique-se de que os campos personalizados sejam nomeados na saída conforme descrito no modelo de dados do aplicativo de processo.

Dica:

Você pode usar os comandos dbt docs para gerar um site de documentação para seu projeto dbt e abri-lo em seu navegador padrão. O site de documentação também contém um gráfico de linhagem que fornece um diagrama de relacionamento de entidade com uma representação gráfica da ligação entre cada tabela de dados em seu projeto.

Para obter informações detalhadas, consulte a documentação oficial do dbt em dbt docs.

Macros

As macros facilitam a reutilização de construções SQL comuns. Para obter informações detalhadas, consulte a documentação oficial do dbt sobre macros Jinja.

pm_utils

O pacote pm-utils contém um conjunto de macros que são normalmente usados em transformações do Process Mining. Para obter mais informações sobre as macros pm_utils , consulte ProcessMining-pm-utils.

Abaixo está um exemplo de código Jinja chamando a macro pm_utils.optional() .

sementes

As semente são arquivos csv que são usados para adicionar tabelas de dados às suas transformações. Para informações detalhadas, consulte a documentação oficial do dbt sobre semente jinja.

Em Process Mining, isso é normalmente usado para facilitar a configuração de mapeamentos em suas transformações.

Depois de editar os arquivos seed, esses arquivos não são atualizados automaticamente no banco de dados imediatamente. Para instruir o dbt a carregar o novo conteúdo do arquivo seed no banco de dados, execute

• dbt seed - que atualizará apenas as tabelas do arquivo seed ou
• dbt build - que também executará todos os modelos e testes.
  Nota: Se o arquivo seed não tiver registros de dados inicialmente, os tipos de dados no banco de dados podem não ter sido configurados corretamente. Para corrigir isso, chame run dbt seed --full-refresh. Isso também atualizará o conjunto de colunas no banco de dados.

Activity configuration

O arquivo activity_configuration.csv é usado para definir campos adicionais relacionados às atividades. activity_order é usado como desempate quando dois eventos estão acontecendo no mesmo carimbo de data/hora. Veja a ilustração abaixo para um exemplo.

Testes

A pasta models\schema\ contém um conjunto de arquivos .yml que definem testes. Estes validam a estrutura e o conteúdo dos dados esperados. Para obter informações detalhadas, consulte a documentação oficial do dbt sobre testes.

Quando as transformações são executadas no Process Mining, apenas os testes em sources.yml são executados em cada ingestão de dados. Isso é feito para verificar se os dados de entrada estão formatados corretamente.

Observação: ao editar transformações, certifique-se de atualizar os testes adequadamente. Os testes podem ser removidos, se desejado.

Métricas personalizadas de tempo de transferência

Introdução

Com a personalização de transformações de dados e edição de painel, você pode criar e usar métricas de tempo de throughput personalizadas. Os tempos de rendimento são as temporizações entre duas atividades A e B. Abaixo está uma descrição das etapas que você precisa executar para criar uma métrica de tempo de rendimento customizado ao editar transformações e como ativar a métrica de tempo de rendimento nos painéis do aplicativo de processo.

Criando uma métrica de tempo de throughput personalizada com transformações de edição

Você deve primeiro calcular o tempo de processamento e, em seguida, disponibilizá-lo como um campo Caso .

Calculando o tempo de processamento

Por caso, você pode calcular os tempos de throughput entre Atividade A e Atividade B. Como as atividades podem ocorrer mais de uma vez por caso, você precisa levar em consideração se considera a primeira ou a última ocorrência de uma atividade.

1. Crie um modelo adicional com base no log de eventos para calcular os tempos de throughput desejados. Por exemplo, Cases_with_throughput_times.

2. Nesse modelo, crie tabelas de pré-processamento nas quais você define quais extremidades do evento deseja usar para os cálculos. Por tabela, você precisa do ID do casoe do fim do evento de uma atividade. Abaixo está um exemplo de como selecionar a última ocorrência da atividade A para um caso.

   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")

   Observação:

   Neste exemplo, se você quiser selecionar a primeira ocorrência da atividade, substitua max por min.

3. Defina a tabela de tempo de throughput juntando as tabelas de pré-processamento ao log de eventos e calculando o tempo real de throughput.

   Dica:

   Você pode usar a função datediff fornecida no pacote pm-utils para calcular a diferença de tempo entre quaisquer dois eventos finais.

   O tempo de transferência deve ser calculado em milissegundos para as instâncias em que a Atividade A precede a Atividade B. Milissegundos são a unidade de tempo usada para definir durações no modelo de aplicativo. Como os tempos de throughput já estão agrupados por caso nas tabelas de pré-processamento, você pode escolher qualquer registro. No exemplo acima, a agregação min é usada. A tabela de tempo de processamento, selecionando o tempo de processamento e uma ID de caso, pode ser definida conforme exibido abaixo.

   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)"

Cálculo do tempo de produtividade em dias excluindo fins de semana

Você pode usar a função date_from_timestamp fornecida no pacote pm-utils para calcular o número de dias entre duas atividades. Além disso, a função diff_weekdays permite que você filtre dias de fim de semana.

Consulte o exemplo de código abaixo para saber como calcular o número de dias úteis entre a Atividade A e a Atividade 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

Cálculo do tempo de produtividade em dias excluindo feriados

Siga as etapas abaixo para calcular o tempo de produtividade em dias entre a Atividade A e a Atividade B , excluindo fins de semana e feriados.

1. Crie um arquivo Holidays.csv para definir os dias que devem ser contados como feriados. O arquivo precisa conter pelo menos um registro para cada feriado. Use o seguinte formato:

feriado	Data	Dia útil
Dia de ano novo	2024-01-01	Sim
Páscoa	31-03-2024	Não
..	..	..

Os registros no arquivo Holidays.csv são usados para contar o número de dias que precisam ser excluídos de um intervalo de datas.

2. Carregue o arquivo Holidays.csv como um arquivo semente no projeto dbt . Para informações detalhadas, consulte a documentação oficial do dbt sobre semente jinja.

3. Calcular o tempo de produtividade em dias excluindo fins de semana usando as funções date_from_timestamp e diff_weekdays fornecidas no pacote pm-utils conforme descrito acima em Cálculo do tempo de produtividade em dias excluindo fins de semana .

4. Calcular o número de registros que são armazenados no arquivo .csv feriados que se enquadram no intervalo de datas fornecido para cada caso. Veja o código de exemplo abaixo.

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"
)

Observação:

No exemplo acima, o filtro Weekday = 'Yes' é usado para não subtrair feriados quando o feriado ocorre em um sábado ou domingo. Isso já foi resolvido na função diff_weekday .

5. Subtraia o número calculado de feriados do número total de dias contados para cada caso. Veja o código de exemplo abaixo.

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"
)

Disponibilizando o tempo de processamento como campo de caso

Depois que a tabela de tempo de processamento é criada, esta tabela precisa ser unida à tabela Casos para adicionar os dados de tempo de processamento adicionais como informações de caso. Para ter o novo campo de tempo de produtividade disponível nos painéis, é necessário converter o novo campo de tempo de produtividade para um dos campos personalizados de duração do caso.

Substitua uma das linhas de duração de caso personalizadas na tabela Casos que se parece com isto:

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

com o tempo de throughput recém-criado:

Cases_with_throughput_times."Throughput_time_activity_A_to_activity_B" as "custom_case_duration_1",

As atualizações nas transformações para a métrica de tempo de throughput customizado agora são feitas e podem ser importadas para o modelo de aplicativo.

Ativando a métrica de tempo de transferência nos painéis do aplicativo de processo

Quando você cria um tempo de rendimento personalizado em suas transformações, ele fica disponível em seu modelo de aplicativo como uma propriedade de caso em seu alias. Você pode personalizar seu aplicativo de processo para criar uma métrica de tempo de rendimento com base no tempo de rendimento personalizado que você criou nas transformações.

Observação:

Por padrão, um novo campo de duração personalizado é adicionado como um campo do tipo numérico. Certifique-se de editar o campo e alterar o Tipo do novo campo para duração. Consulte também Gerenciador de dados.

• Acesse Data Manager e crie uma métrica.
• Selecione o campo de duração personalizado a ser usado para o tempo de rendimento e selecione Média ou qualquer outra agregação desejada. Você também pode renomear o campo personalizado de duração do caso com o nome desejado no Gerenciador de dados.
• Edite o aplicativo e coloque a nova métrica nos gráficos onde deseja disponibilizá-la para usuários corporativos.
• Publique os painéis para disponibilizar a métrica de tempo de rendimento nos painéis.

Observação:

Nos modelos de aplicativo Purchase-to-Pay e Order-to-Cash, um cálculo de tempo de processamento já está disponível em Purchase_order_items_with_throughput_times e Sales_order_items_with_throughput_times, respectivamente. Tempos de produção customizados podem ser adicionados lá e disponibilizados como uma duração customizada em Purchase_order_items ou Sales_order_items.

SQL differences between Snowflake and SQL Server

SQL Server vs. Snowflake

Em um ambiente de desenvolvimento local, as transformações são executadas no SQL Server, enquanto o Snowflake é usado no Process Mining Automation Suite. Embora a maioria das instruções SQL funcione no SQL Server e no Snowflake, pode haver pequenas diferenças na sintaxe, o que pode levar a resultados retornados diferentes.

Para escrever instruções SQL que funcionem em ambos os sistemas de banco de dados:

• Escreva os nomes dos campos entre aspas duplas, por exemplo Table."Field".
• Evite o uso de funções SQL diferentes no Snowflake e no SQL Server, por exemplo string_agg() e listagg().
  O pacote pm_utils vem com um conjunto de funções que funcionam em ambos os tipos de banco de dados, consulte Vários bancos de dados. Por exemplo, em vez de usar string_agg() ou listagg(), o pm_utils.string_agg() resultará no mesmo comportamento para ambos os bancos de dados. Se pm_utils não contiver a função desejada, uma instrução Jinja deverá ser criada para garantir que a função correta seja chamada em cada banco de dados.

Concatenação de strings

Para combinar strings, use a função pm_utils.concat() . Isso produzirá os mesmos resultados para SQL Server e Snowflake.

Exemplo: pm_utils.concat("This is a nice string", null) = "This is a nice string" A concatenação de strings não deve ser feita com operadores como + ou ||, pois são diferentes para ambos os bancos de dados (Snowflake usa || e SQL Server usa +). Além disso, a função concat() padrão tem comportamento diferente em ambos os sistemas:

SQL Server	Snowflake
Os valoresnull serão ignorados e tratados como uma string vazia.	Valoresnull farão com que todo o resultado seja null.

Ordenação

A classificação é tratada de forma diferente no Snowflake e no SQL Server.

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

Valores nulos

SQL Server	Snowflake
null padrão será classificado primeiro (crescente)	null por padrão será ordenado por último (ascendente)

Handling capital letters

SQL Server	Snowflake
as maiúsculas são classificadas como esperado (AaBbCc)	primeiro classifica por maiúsculas, depois por não maiúsculas (ABCabc)

Dashes

Exemplo: -Accountant-

SQL Server	Snowflake
travessões são ignorados na classificação (portanto, '-Contador-' é tratado da mesma forma que 'Contador')	os traços serão classificados no topo

Manuseio de espaço em branco

Quando você agrupa por valores “A“ e “ A“, isso é visto como um valor no SQL Server, mas como dois valores diferentes no Snowflake. Portanto, o corte é recomendado se seus dados puderem causar esse problema.

Diferenciação de maiúsculas e minúsculas

Por padrão, o SQL Server não diferencia maiúsculas de minúsculas, enquanto o Snowflake diferencia maiúsculas de minúsculas. Isso significa que Table."Field" = "Some_value" e Table."Field" = "SOME_VALUE" retornarão o mesmo conjunto de resultados no SQL Server, mas possivelmente dois conjuntos de resultados diferentes no Snowflake.

É recomendável alterar o comportamento do banco de dados local do SQL Server para corresponder ao comportamento do Snowflakes, a fim de evitar problemas. Isso pode ser feito definindo o agrupamento do banco de dados para um valor que diferencia maiúsculas de minúsculas.

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.

Ao criar um aplicativo de processo, certifique-se sempre de que os dados de entrada estejam no formato necessário para o modelo de aplicativo usado para criar um aplicativo. Consulte Modelos de aplicativo.

Importante:

Novos aplicativos de processo serão aplicados ao novo modelo de dados por padrão. Os aplicativos de processos existentes continuarão a funcionar no Process Mining 2023.4 e no Process Mining 2023.10. Troque as configurações de carregamento de dados dos seus apps de processo antes do Process Mining 2024.4, para garantir que o carregamento de dados continue funcionando corretamente. As configurações AddRawTablePostfix e StripSpecialCharacters são temporárias e serão removidas no Process Mining 2024.4. A partir de então, todos os aplicativos de processo funcionarão como se essas configurações fossem definidas como falsas.

Configuração	Format	Description
AddRawTablePostfix	Booleano	Para adicionar um sufixo _raw às suas tabelas de origem ao usar uploads de arquivo por meio da opção Carregar dados . Por exemplo, se o arquivo carregado tiver o nome Event_log.csv , ele será alterado para Event_log_raw.csv se essa configuração for definida como true.
StripSpecialCharacters	Booleano	Para remover caracteres especiais e substituir espaços por sublinhados em nomes de tabelas e/ou nomes de campos. Por exemplo, um campo chamado Event+end muda para Eventend.

Usando aplicativos de processo existentes com as novas configurações de modelo de dados

Siga estas etapas para usar seus aplicativos de processo existentes com as novas configurações de modelo de dados.

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

2. Exporte as transformações de seu aplicativo de processo. Consulte Edição de transformações de dados em um ambiente local.

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

4. Certifique-se de que AddRawTablePostfix e StripSpecialCharacters estejam definidos como false.

5. Altere seus arquivos de entrada, ou transformações, de forma que os nomes dos arquivos correspondam exatamente. Por exemplo, se suas transformações de entrada esperam event_log_raw , seu arquivo csv também deve ser chamado event_log_raw.csv.

6. Se você estiver usando caracteres especiais em nomes de tabela ou nomes de campo (por exemplo ' ', '(' ou '?'), certifique-se de que as transformações de entrada usem o mesmo nome. Por exemplo, uma categoria de atividade de campo deve ser referida como categoria de atividade em suas consultas e não como Activity_category.

7. Importe transformações e ingira novos dados.

As transformações serão executadas novamente na plataforma e as tabelas de origem serão alteradas de acordo.

Projetos dbt

As transformações de dados são usadas para transformar dados de entrada em dados adequados para o Process Mining. As transformações no Process Mining são escritas como projetos dbt .

Esta página apresenta uma introdução ao dbt. Para obter informações mais detalhadas, consulte a documentação oficial do dbt.

pm-utils package

Os modelos de aplicativos do Process Mining vêm com um pacote dbt chamado pm_utils. Este pacote pm-utils contém funções e macros de utilitário para projetos de dbt do Process Mining. Para obter mais informações sobre o pm_utils , consulte ProcessMining-pm-utils.

Atualização da versão pm-utils usada para seu modelo de aplicativo

A UiPath® aprimora constantemente o pacote pm-utils , adicionando novas funções.

Quando uma nova versão do pacote pm-utils é lançada, é recomendável atualizar a versão usada em suas transformações para garantir que você esteja usando as funções e macros mais recentes do pacote pm-utils .

Você encontra o número da versão mais recente do pacote pm-utils no painel Versões do ProcessMining-pm-utils.

Siga estas etapas para atualizar a versão pm-utils em suas transformações.

1. Baixe o código-fonte (zip) da versão de pm-utils.
2. Extraia o arquivo zip e renomeie a pasta para pm_utils.

3. Exporte as transformações do editor de transformações de dados embutidos e extraia os arquivos.

4. Substitua a pasta pm_utils das transformações exportadas pela nova pasta pm_utils .

5. Compacte o conteúdo das transformações novamente e importe-as no editor Transformações de dados .