Editing transformations

Estrutura da pasta

The transformations of a process app consist of a dbt project. Below is a description of the contents of a dbt project folder.

Pasta/Arquivo	Contém
dbt_packages\	o pacote pm_utils e suas macros.
logs\	logs created when running 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_objects,
• 3_events,
• 4_event_logs,
• 5_business_logic.

Confira Estrutura das transformações.

The .sql files are written in Jinja SQL, which allows you to insert Jinja statements inside plain SQL queries. When dbt runs all .sql files, each .sql file results in a new view or table in the database.

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

1. Instruções Com: uma ou mais instruções com 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 a criação de subseleções durante a depuração.

   

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

Adição de tabelas de origem

To add a new source table to the dbt project, it must be listed in models\schema\sources.yml. This way, other models can refer to it by using {{ source(var("schema_sources"), 'My_table_raw') }}. See the illustration below for an example.

Importante:

Each new source table must be listed in sources.yml.

Observação:

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

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

Saída de dados

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 normalmente são usadas em transformações do Process Mining. Para obter mais informações sobre as macros pm_utils , consulte ProcessMining-pm-utils.

A ilustração a seguir mostra um exemplo de código Jinja chamando a macro pm_utils.optional() .

sementes

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

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

After editing seed files, these files are not automatically updated in the database immediately. To instruct dbt to load the new seed file contents into the database, run either

• dbt seed - que atualizará apenas as tabelas do arquivo seed ou

• dbt build - que também executará todos os modelos e testes.

  Observação:

  If the seed file had no data records initially, the data types in the database might not have been set correctly. To fix this, call run dbt seed --full-refresh. This will also update the set of columns in the database.

Activity configuration

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

Testes

A pasta models\schema\ contém um conjunto de arquivos .yml que definem os 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:

When you edit transformations, make sure to update the tests accordingly. The tests can be removed if desired.

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 personalizadas de tempo de produtividade. Tempos de produtividade são os tempos entre duas atividades A e B. As seções a seguir descrevem as etapas que você precisa executar para criar uma métrica de tempo de produtividade personalizada ao editar transformações e como habilitar a métrica de tempo de produtividade 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 produtividade e, em seguida, disponibilizá-lo como um campo Caso.

Calculando o tempo de processamento

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

1. Crie um modelo adicional com base no Log de evento para calcular os tempos de produtividade desejados. Por exemplo, Cases_with_production_times.

2. Neste modelo, crie tabelas de pré-processamento nas quais você define quais fins de evento deseja usar para as computações. Por tabela, você precisa do ID do caso e do Fim do evento de uma atividade. O código a seguir mostra 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 produtividade associando as tabelas de pré-processamento ao Log de evento e calculando o tempo de produtividade real.

   Dica:

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

   O tempo de produtividade deve ser calculado em milissegundos para as instâncias em que a Atividade A precede a Atividade B. Milissegundos é a unidade de tempo usada para definir durações no modelo de aplicativo. Como os tempos de produtividade já estão agrupados por caso nas tabelas de pré-processamento, você pode escolher qualquer registro. No exemplo acima, agregação min é usada. A tabela de tempo de produtividade, selecionando o tempo de produtividade e um ID de caso, pode ser definida como exibida no bloco de código a seguir.

   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.

O exemplo de código a seguir mostra 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 estas etapas para calcular o tempo de produtividade em dias entre a Atividade A e a Atividade B, excluindo dias de fim de semana e feriados.

1. Crie um arquivo Holidays.csv para definir os dias que devem ser contados como feriados. O arquivo deve 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 obter informações detalhadas, consulte a documentação oficial do dbt sobre sementes jinja.

3. Calcule 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. Calcule o número de registros armazenados no arquivo de feriados .csv que estão dentro do intervalo de datas fornecido para cada caso. O código a seguir mostra um exemplo.

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 calculados para cada caso. O código a seguir mostra um exemplo.

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

Após a tabela de tempo de produtividade ser criada, essa tabela precisa ser associada à tabela Casos para adicionar os dados de tempo de produtividade adicionais como informação de caso. Para ter o novo campo Tempo de produtividade disponível nos painéis, é necessário converter o novo campo Tempo de produtividade para um dos campos de duração de casos personalizados.

Substitua uma das linhas de duração de caso personalizadas na tabela Casos que tenha a seguinte aparência:

{{ 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 o 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 produtividade e selecione Média ou qualquer outra agregação desejada. Você também pode renomear o campo personalizado de duração de caso com o nome desejado no Data Manager.
• 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 aplicativos Purchase-to-Pay e Order-to-Cash, um cálculo de tempo de produtividade já está disponível em Purchase_order_items_with_ pro Os tempos de produtividade personalizados podem ser adicionados lá e, em seguida, serem disponibilizados como uma duração personalizada nos Purchase_order_items ou Sales_order_items.

Diferenças de SQL entre o Snowflake e o SQL Server

SQL Server vs. Snowflake

Em um ambiente de desenvolvimento local, as transformações são executadas no SQL Server, enquanto que o Snowflake é usado no Process Mining Automation Cloud. Embora a maioria das instruções SQL funcione tanto no SQL Server quanto no Snowflake, pode haver pequenas diferenças na sintaxe, o que pode levar a resultados com retornos 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(), 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
null os valores serão ignorados e tratados como uma string vazia.	null os valores 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 o padrão será ordenado primeiro (crescente)	null o padrão será classificado por último (crescente)

Manuseio de letras maiúsculas

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

O arquivo settings.json contém configurações relacionadas ao carregamento de dados de entrada. Essas configurações são temporárias e devem ser usadas para alternar aplicativos de processo existentes (criados antes de março de 2023) para o novo comportamento de carregamento de dados. Você não deve alterar o arquivo settings.json para novos apps de processo.

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:

Por padrão, novos aplicativos de processo serão aplicados ao novo modelo de dados. Os aplicativos de processo existentes continuarão funcionando no Process Mining 2023.4 e no Process Mining 2023.10. Mude as configurações de carregamento de dados de seus aplicativos de processo antes do Process Mining 2024.4, para garantir que o carregamento de dados continue funcionando corretamente. As configurações de AddRawTablePostfix e de 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 estivessem definidas como false.

Configuração	Format	Description
AddRawTablePostfix	Booleano	Para adicionar um sufixo _raw às suas tabelas de origem ao usar uploads de arquivos por meio da opção Carregar dados . Por exemplo, se o arquivo que você está carregando for nomeado 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 tabela e/ou nomes de campo. Por exemplo, um campo chamado Event+end altera o 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. Baixe o settings.json.zip e descompacte o arquivo .
2. Exporte as transformações de seu aplicativo de processo.
3. Adicione o arquivo settings.json (se já não estiver presente) às transformações.
4. Certifique-se de que AddRawTablePostfix e StripSpecialCharacters estejam definidos como false.
5. Altere seus arquivos de entrada ou transformações, de modo que os nomes dos arquivos correspondam exatamente. Por exemplo, se suas transformações de entrada esperam event_log_raw, então seu arquivo csv também deve ser chamado event_log_raw.csv.
6. Se você estiver usando caracteres especiais em nomes de tabelas ou de campos (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 de Activity_category.
7. Importe transformações e carregue 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 fornece uma introdução ao dbt. Para 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. Esse pacote pm-utils contém funções utilitárias e macros para projetos 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® melhora 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 para a pasta pm_utils.
3. Exporte as transformações do editor de transformações de dados em linha 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-o no editor Transformações de dados .