Sobre a ferramenta Migrador de atividades

Migre projetos de automação legados para a UiPath Platform moderna usando a ferramenta de CLI Activity Migrator.

Finalidade da ferramenta de migração de atividades

A ferramenta de migração de atividades é uma ferramenta de interface de linha de comando (CLI) essencial para organizações que fazem a transição de projetos de automação legados para a moderna UiPath Platform, permitindo o acesso às funcionalidades e recursos mais recentes:

• Automatize o processo de migração ao simplificar e agilizar a transferência da configuração e das dependências do processo.
• Reduza o esforço manual e os erros garantindo a consistência e a precisão durante a migração, em vez de transferir dependências e atividades manualmente.

Cenários de migração compatíveis

Migração da estrutura do projeto

Recomendamos fortemente a migração de um projeto do Windows - Legacy para compatibilidade com o Windows por vários motivos estratégicos, técnicos e relacionados ao suporte:

1. Desempenho aprimorado: os projetos do Windows são executados de forma mais rápida e eficiente devido à melhor integração com o .NET Core e APIs modernas do Windows.
2. Melhor compatibilidade com bibliotecas externas: os projetos do Windows são compatíveis com versões mais recentes de bibliotecas e dependências, facilitando a integração com sistemas externos.

Acesso a recursos modernos de UI Automation

Muitos novos recursos de UI Automation, como Destino unificado e Healing Agent, são compatíveis apenas com o framework de UI Automation moderno.Portanto, você deve migrar das atividades clássicas de UI Automation para a experiência moderna.

Migração de atividades obsoletas do Outlook

A Microsoft está encerrando o Outlook clássico e incentivando a adoção do Microsoft 365.Como resultado, a ferramenta de migração de atividades é compatível com a transição de dependências de automação de UiPath.Mail.Activities (que dependem da API Classic Outlook) para UiPath.MicrosoftOffice365.Activities dependências baseadas no UiPath Integration Service.

Migração de atividades do GSuite

Para se beneficiar dos aprimoramentos mais recentes, recomendamos usar as atividades do Google Workspace baseadas em conexões do Integration Service. O Migrador de atividades é compatível com a conversão de atividades clássicas em atividades modernas dentro do mesmo pacote UiPath.GSuite.Activities. Essas atividades modernas automatizam aplicativos do Google Workspace (anteriormente conhecidos como GSuite), abrangendo seis serviços: Gmail, Calendário, Drive, Docs, Planilhas e Apps Script.

Ferramenta de migração de atividades versus Studio Windows - Conversor legado

Use o conversor Studio Windows - Legacy quando:

• Você só precisar converter projetos do Windows - Legacy para Windows um por um.
• Não são necessárias migrações de atividades.

Use a ferramenta de migração de atividades quando:

• Você desejar converter vários projetos do Windows - Legacy para Windows (conversão em massa compatível).
• A migração de atividades UI Automation, Mail ou GSuite clássica é necessária.
• Qualquer combinação dos cenários acima é aplicável.

Onde obter a ferramenta de migração de atividades

Siga as etapas a seguir para baixar a ferramenta:

1. Navegue até o UiPath Automation Cloud.
2. Selecione o botão Ajuda no canto superior direito.
3. Em Recursos, selecione Downloads.
4. Na lista Download em destaque , selecione Ferramenta de migração de atividade.
5. Selecione o link de download.

Resultado

O arquivo .zip do Migrador de Atividade é baixado para sua máquina. Extraia-o e instale a ferramenta na pasta <tool-install-dir> antes de executar quaisquer comandos.

Requisitos

• Se a ferramenta for usada em uma máquina em que o Studio não está instalado, instale o .NET Desktop Runtime 8.0.
• Abrir projetos migrados com versões do Studio 2024.10 ou posteriores.

Como usar a ferramenta de migração de atividades

Comando: <tool-install-dir>\UiPath.Upgrade.exe

Uso: UiPath.Upgrade.exe [command] [options]

Opções globais

Opção	Description
-?, -h, --help	Mostrar informações de ajuda e uso.

Comandos disponíveis

Command	Description
version	Mostrar informações da versão.
analyze	Analisar um projeto para migração sem fazer alterações.
upgrade	Migre um projeto ou partes dele.
bulk	Analise ou migre todos os projetos para uma pasta.

Analisar um projeto

Essa opção simula a migração e gera um relatório sem executar a migração real ou modificar o projeto.

Comando: <tool-install-dir>\UiPath.Upgrade.exe analyze

Uso: UiPath.Upgrade.exe analyze [options]

Opção	Description
-?, -h, --help	Mostrar informações de ajuda e uso.
-p, --project-path (obrigatório)	Caminho para o projeto a ser analisado ou atualizado. A pasta fornecida como <project-path> deve conter o arquivo project.json do projeto.
-o, --output-path	Caminho de saída para o projeto atualizado (opcional). Se não for especificado, o sistema cria uma nova pasta com o sufixo _Upgraded.
-v, --verbose	Habilitar o registro Verbose.
-f, --output-format	Formato de saída: console (padrão) ou sarif.
-e, --extension-directory	Diretório para pesquisar extensões. Apenas para uso avançado.
--ignore-missing-dependencies	Ignorar dependências ausentes durante a atualização. As dependências ausentes aparecem como avisos. Os fluxos de trabalho afetados podem relatar tipos ausentes, não compilar ou não executar outras migrações necessárias.
--orchestrator-url	A URL do Orchestrator completa, incluindo o nome da organização (por exemplo, https://cloud.uipath.com/myorg).Se não for especificada, usa-se a conexão do Studio. Quando especificado, você também deve fornecer credenciais por meio do Token de acesso pessoal (PAT) usando --orchestrator-pat ou ID do Aplicativo externo e segredo usando --orchestrator-application-id e --orchestrator-application-secret.
--orchestrator-tenant	O nome do tenant do Orchestrator. O valor padrão é DefaultTenant se não for especificado.
--orchestrator-pat	Token de acesso pessoal (PAT) para autenticação do Orchestrator, usado para acessar feeds de bibliotecas do Orchestrator. Crie um Token de acesso pessoal e adicione escopo de acesso à API do Orchestrator OR.Execution.Read. Consulte Tokens de acesso pessoal. Ou configure uma ID do aplicativo e um segredo usando --orchestrator-application-id e --orchestrator-application-secret.
--orchestrator-application-id	ID do Aplicativo OAuth para autenticação do Orchestrator (alternativa ao PAT). Use com --orchestrator-application-secret. Consulte Gerenciamento de aplicativos OAuth externos.
--orchestrator-application-secret	Segredo do aplicativo OAuth para autenticação do Orchestrator (alternativa ao PAT). Use com --orchestrator-application-id. Consulte Gerenciamento de aplicativos OAuth externos.
--enabled-extensions	Lista separada por vírgulas de extensões a serem habilitadas. Consulte Extensões disponíveis.
--disabled-extensions	Lista de extensões a serem desabilitadas separada por vírgulas. As extensões disponíveis são preenchidas dinamicamente com base em extensões descobertas.
--disable-all-extensions	Desabilite todas as extensões. Essa opção é mutuamente exclusiva com --enabled-extensions e --disabled-extensions.
--uia-package-version	A versão do pacote de atividades do UI Automation para usar na migração.O padrão é 25.10.21 se não especificado. A versão de destino deve ser superior ao padrão. Se não, o padrão é usado.
--uia-fix-selector-strategy	Quando definido como true, corrige a ambiguidade de enumeração SelectorStrategy em expressões pré-existentes após a migração. Aplica-se à versão 25.10.29 ou posterior do UIAutomation. Padrão: (false). A ambiguidade resulta da enumeração SelectorStrategy existente nos namespaces UiPath.Core e UiPath.UIAutomationNext.Enums. O uso do nome totalmente qualificado resolve esse problema.
--uia-enable-partial-migration	Migre atividades mesmo quando a compatibilidade total não puder ser garantida. A migração gera o equivalente compatível mais próximo, que pode exigir ajustes manuais para funcionar corretamente. Requer o pacote UIAutomation 25.10.38 ou posterior (consulte --uia-package-version). Essa opção é ignorada ao usar versões anteriores do pacote. Padrão: false.
--mail-o365-package-version	A versão do pacote de atividades do Microsoft Office 365 a ser usada na migração. O padrão é a versão 3.6.10. A versão de destino deve ser superior ao padrão. Se não, o padrão é usado.
--config, --mail-config	Especifica o caminho para um arquivo JSON de configuração personalizado. A configuração pode ser usada para modificar o comportamento padrão de certas atividades ou atribuir valores constantes a propriedades que exigem entrada do usuário durante a migração. Consulte Arquivo de configuração.
--gsuite-package-version	A versão do pacote de atividades UiPath.GSuite.Activities a ser usada para migração. O padrão é a versão 3.8.10, se não for especificada. A versão de destino deve ser posterior à versão padrão. Se a versão de destino for inferior, a versão padrão será usada.
--gsuite-config	Especifica o caminho para um arquivo JSON de configuração personalizado. A configuração pode ser usada para modificar o comportamento padrão de certas atividades ou atribuir valores constantes a propriedades que exigem entrada do usuário durante a migração. Consulte Arquivo de configuração.
--gsuite-migrate-only	Lista separada por vírgulas de serviços incluídos na migração do GSuite (com diferenciação de maiúsculas e minúsculas). Valores disponíveis: gmail, calendar, drive, docs, sheets, appsscript. Se especificado, apenas esses serviços serão executados.

Migrar um projeto

Essa opção executa a migração real de um projeto ou de partes dele.

Comando: <tool-install-dir>\UiPath.Upgrade.exe upgrade

Uso: UiPath.Upgrade.exe upgrade [options]

Opção	Description
-?, -h, --help	Mostrar informações de ajuda e uso.
-p, --project-path (obrigatório)	Caminho para a pasta que contém o arquivo project.json do projeto.
-o, --output-path	Caminho de saída para o projeto atualizado (opcional). Se não for especificado, o sistema cria uma nova pasta com o sufixo _Upgraded.
-v, --verbose	Habilitar o registro Verbose.
-f, --output-format	Formato de saída: console (padrão) ou sarif.
-e, --extension-directory	Diretório para pesquisar extensões. Apenas para uso avançado.
--ignore-missing-dependencies	Ignorar dependências ausentes durante a atualização. As dependências ausentes aparecem como avisos. Os fluxos de trabalho afetados podem relatar tipos ausentes, não compilar ou não executar outras migrações necessárias.
--orchestrator-url	A URL completa do Orchestrator, incluindo o nome da organização. Se não for especificada, usa-se a conexão do Studio. Quando especificadas, as credenciais são necessárias.
--orchestrator-tenant	O nome do tenant do Orchestrator. O valor padrão é DefaultTenant se não for especificado.
--orchestrator-pat	Token de acesso pessoal (PAT) para autenticação do Orchestrator. Requer o escopo OR.Execution.Read.
--orchestrator-application-id	ID do Aplicativo OAuth para autenticação do Orchestrator (alternativa ao PAT).
--orchestrator-application-secret	Segredo do aplicativo OAuth (alternativa ao PAT).
--enabled-extensions	Lista separada por vírgulas de extensões a serem habilitadas. Consulte Extensões disponíveis.
--disabled-extensions	Lista de extensões a serem desabilitadas separada por vírgulas. As extensões disponíveis são preenchidas dinamicamente com base em extensões descobertas.
--disable-all-extensions	Desabilite todas as extensões. Mutuamente exclusivos com --enabled-extensions e --disabled-extensions.
--uia-package-version	Versão UiPath.UIAutomation.Activities do pacote de destino. O padrão é 25.10.21.
--uia-fix-selector-strategy	Quando definido como true, corrige a ambiguidade de enumeração SelectorStrategy em expressões pré-existentes após a migração. Aplica-se à versão 25.10.29 ou posterior do UIAutomation. Padrão: (false). A ambiguidade resulta da enumeração SelectorStrategy existente nos namespaces UiPath.Core e UiPath.UIAutomationNext.Enums. O uso do nome totalmente qualificado resolve esse problema.
--uia-enable-partial-migration	Migre atividades mesmo quando a compatibilidade total não puder ser garantida. A migração gera o equivalente compatível mais próximo, que pode exigir ajustes manuais para funcionar corretamente. Requer o pacote UIAutomation 25.10.38 ou posterior (consulte --uia-package-version). Essa opção é ignorada ao usar versões anteriores do pacote. Padrão: false.
--mail-o365-package-version	A versão do pacote de atividades do Microsoft Office 365 a ser usada na migração. O padrão é a versão 3.6.10. A versão de destino deve ser superior ao padrão. Se não, o padrão é usado.
--config, --mail-config	Especifica o caminho para um arquivo JSON de configuração personalizado. A configuração pode ser usada para modificar o comportamento padrão de certas atividades ou atribuir valores constantes a propriedades que exigem entrada do usuário durante a migração. Consulte Arquivo de configuração.
--gsuite-package-version	A versão do pacote de atividades UiPath.GSuite.Activities a ser usada para migração. O padrão é a versão 3.8.10, se não for especificada. A versão de destino deve ser posterior à versão padrão. Se a versão de destino for inferior, a versão padrão será usada.
--gsuite-config	Especifica o caminho para um arquivo JSON de configuração personalizado. A configuração pode ser usada para modificar o comportamento padrão de certas atividades ou atribuir valores constantes a propriedades que exigem entrada do usuário durante a migração. Consulte Arquivo de configuração.
--gsuite-migrate-only	Lista separada por vírgulas de serviços incluídos na migração do GSuite (com diferenciação de maiúsculas e minúsculas). Valores disponíveis: gmail, calendar, drive, docs, sheets, appsscript. Se especificado, apenas esses serviços serão executados.

Migração de repositório em massa

Essa opção analisa ou migra todos os projetos encontrados em uma hierarquia de pastas.

Comando: <tool-install-dir>\UiPath.Upgrade.exe bulk

Uso: UiPath.Upgrade.exe bulk [options]

Opção	Description
-?, -h, --help	Mostrar informações de ajuda e uso.
-p, --path (obrigatório)	Caminho para o repositório ou pasta. A migração ocorre em todas as subpastas que contêm um arquivo project.json.
-c, --command (obrigatório)	Comando a executar: analyze ou upgrade.
-v, --verbose	Habilitar o registro Verbose.
-o, --output-path	Caminho raiz de saída para projetos atualizados. Essa pasta é criada se não existir.O sistema cria uma nova pasta com o sufixo _Upgraded para o projeto atualizado.
--orchestrator-url	A URL do Orchestrator completa, incluindo o nome da organização.
--orchestrator-tenant	O nome do tenant do Orchestrator. O valor padrão é DefaultTenant se não for especificado.
--orchestrator-pat	Token de acesso pessoal (PAT) para autenticação do Orchestrator. Requer o escopo OR.Execution.Read.
--orchestrator-application-id	ID do Aplicativo OAuth para autenticação do Orchestrator (alternativa ao PAT).
--orchestrator-application-secret	Segredo do aplicativo OAuth (alternativa ao PAT).
--enabled-extensions	Lista separada por vírgulas de extensões a serem habilitadas. Consulte Extensões disponíveis.
--disabled-extensions	Lista de extensões a serem desabilitadas separada por vírgulas. As extensões disponíveis são preenchidas dinamicamente com base em extensões descobertas.
--disable-all-extensions	Desabilite todas as extensões. Mutuamente exclusivos com --enabled-extensions e --disabled-extensions.

Exemplos

Analise um único projeto com saída detalhada:

UiPath.Upgrade.exe analyze -p C:\to-migrate\LegacyProcess -v

Migre um projeto e especifique uma versão do pacote de UI Automation de destino:

UiPath.Upgrade.exe upgrade -p C:\to-migrate\LegacyProcess -o C:\to-migrate\WindowsProcess --uia-package-version=25.10.27 -v

Migre um projeto usando uma configuração de conexão personalizada:

UiPath.Upgrade.exe upgrade --project-path=C:\to-migrate\LegacyProcess --config=C:\to-migrate\connection.json

Execute uma análise em massa em uma pasta:

UiPath.Upgrade.exe bulk -p C:\to-migrate -c analyze

Migre apenas atividades clássicas de Email e GSuite no projeto, sem tocar em outras atividades, como atividades clássicas de Automação de Interface Gráfica:

UiPath.Upgrade.exe upgrade --project-path="C:\To Migrate\LegacyProcess" --enabled-extensions=MailActivities,GSuiteActivities

Migre apenas o projeto legado para o Windows (o mesmo que o Studio Windows - Conversão legada). O comando não migra nenhum dos tipos de atividades compatíveis:

UiPath.Upgrade.exe upgrade -p "C:\To Migrate\LegacyProcess" -o "C:\To Migrate\WindowsProcess" --disable-all-extensions

Observação:

• As opções de linha de comando usam as seguintes convenções:
  • As opções curtas (por exemplo, -p value) devem usar um espaço para separar a opção de seu valor.
  • As opções longas (por exemplo, --project-path=value) normalmente usam o sinal de igual para vincular explicitamente o valor ao parâmetro específico.Na maioria dos casos, as opções longas também podem ser especificadas usando um espaço (por exemplo, --project-path value). A opção --config é uma exceção e é compatível apenas com a sintaxe de sinal de igual (por exemplo, --config=value).
• A saída padrão do comando upgrade é um relatório SARIF armazenado no projeto original em uma pasta .upgrade. O sistema salva o projeto migrado no caminho de saída.

Sintaxe compatível com coleções

Várias opções de CLI aceitam valores de coleção: --enabled-extensions, --disabled-extensions e --gsuite-migrate-only. Cada um é compatível com várias sintaxes para especificar valores.

Formatos suportados

Por exemplo, todos eles vinculam os mesmos valores à ["drive", "gmail"] coleção:

• Separados por vírgula: --gsuite-migrate-only=drive,gmail ou --gsuite-migrate-only=drive --gsuite-migrate-only=gmail
• Separado por espaço: --gsuite-migrate-only drive,gmail ou --gsuite-migrate-only drive --gsuite-migrate-only gmail
• Sintaxe de dois pontos (menos comum): --gsuite-migrate-only:drive,gmail
• Sintaxe mista: --gsuite-migrate-only=drive --gsuite-migrate-only gmail

Comportamento padrão

Se a opção estiver ausente do comando:

• --gsuite-migrate-only - migra todos os serviços do Google Workspace
• --enabled-extensions - todas as extensões estão habilitadas
• --disabled-extensions- nenhuma extensão está desabilitada

Observação:

Especificar uma ocorrência sem valores (por exemplo, --gsuite-migrate-only "") é rejeitada pelo validador.

Extensões disponíveis

As seguintes extensões podem ser especificadas para a opção --enabled-extensions ou --disabled-extensions:

Extensão	Description
UiAutomationActivities	Migra as atividades clássicas de Automação de Interface Gráfica no pacote UiPath.UIAutomation.Activities para atividades modernas de Automação de Interface Gráfica.
MailActivities	Migra dependências de UiPath.Mail.Activities (atividades clássicas baseadas no Outlook) para UiPath.MicrosoftOffice365.Activities (atividades baseadas no Integration Service).
MicrosoftActivitiesExtension	Tenta converter atividades do pacote Microsoft.Activities.Extensions , que funciona apenas no.NET Framework (Legado).
GSuiteActivities	Migra as atividades clássicas do GSuite no pacote UiPath.GSuite.Activities para atividades modernas dentro do mesmo pacote.

Exemplo: --enabled-extensions MailActivities,GSuiteActivities

Por padrão, todas as extensões estão habilitadas. Se a --enabled-extensions opção não for analyze especificada, upgrade os bulk comandos, e processarão todas as atividades nos pacotes compatíveis.

Arquivo de configuração

Use um arquivo de configuração para definir valores constantes para propriedades de atividades que exigem entrada manual durante a migração ou para substituir o comportamento de migração padrão.

Passe o caminho do arquivo para o migrador usando a opção --config com o operador de atribuição, = como neste exemplo: --config=C:\to-migrate\connection.json. Você deve usar a opção de configuração apropriada, dependendo do tipo de migração:

• Para migração de atividades do Outlook Mail: --config ou --mail-config
• Para migração de atividades do GSuite clássico: --gsuite-config

O arquivo de configuração deve seguir este formato:

{
  "{reserved-configuration-key}": "{value}",
  "...": "...",
  "{path-to-workflow} > [{connector-type}] {activity-display-name}": {
    "{property-name}": "{property-value}"
  }
}

Observações especiais

• O único {property-name} que pode ser atribuído é ConnectionId.
• * atua como um curinga e corresponde a qualquer valor em {path-to-workflow}, {connector-type} e {activity-display-name}. Assim, vários fluxos de trabalho ou atividades podem ser especificados para a mesma coleção de propriedades. Quando várias entradas correspondem ao mesmo fluxo de trabalho, atividade ou tupla de conector, apenas a última correspondência é aplicada.
• A parte [{connector-type}] é opcional. Quando omitida, a entrada corresponde a qualquer atividade, independentemente do tipo de conector. Quando especificada, a entrada corresponde apenas a atividades associadas a esse conector. Pelo menos [{connector-type}] ou {activity-display-name} deve estar presente.

Chaves de configuração reservadas

{reserved-configuration-key} representa alterações de comportamento específicas da atividade:

• SaveOutlookMailMessage_IgnoreSaveAsType: se definida como true, a opção desabilita a verificação Save as type para tipos não compatíveis. Assim, a atividade pode ser migrada independentemente de Save as type option.

Tipos de conector disponíveis

Os seguintes tipos de conector podem ser usados com o padrão [{connector-type}]:

Conectores do Google (GSuite):

• uipath-google-drive: conector do Google Drive
• uipath-google-docs: conector do Google Docs
• uipath-google-sheets: conector do Google Spreadsheets
• uipath-google-gmail: conector do Gmail
• uipath-google-workspace: conector do Google Workspace
• uipath-google-tasks: conector do Google Tasks
• uipath-google-forms: conector do Google Forms

Conectores Microsoft:

• uipath-microsoft-outlook365: conector do Microsoft Outlook 365 Graph
• uipath-microsoft-outlook365ews: conector do Microsoft Outlook 365 EWS (Exchange Web Services)
• uipath-microsoft-onedrive: conector do Microsoft OneDrive
• uipath-microsoft-365: conector do Microsoft Office 365
• uipath-mail-mail: conector de e-mail

Obtenção da ConnectionId do Orchestrator

A partir de março de 2026, as conexões mudaram do Integration Service para o Orchestrator. Você pode recuperar o ConnectionId diretamente da URL de conexão no Orchestrator:

1. Navegue até sua conexão no Orchestrator: acesse a pasta do Orchestrator onde sua conexão do Microsoft Outlook 365 está localizada.
2. Abrir a conexão: selecione a conexão para visualizar seus detalhes.
3. Verifique a URL: o ConnectionId está visível na URL do navegador com o seguinte formato: https://cloud.uipath.com/{OrganizationName}/{TenantName}/orchestrator_/connections/{ConnectionId}/edit/tid={TId}

Resultado

O ID da conexão é visível no URL do navegador no formato .../connections/{ConnectionId}/edit/tid={TId}.

Configuração de IDs de conexão para atividades de Email

A propriedade ConnectionId não é preenchida automaticamente durante a migração. Você deve defini-lo manualmente por fluxo de trabalho/atividade usando um arquivo de configuração. O arquivo de configuração pode ser passado para o Migrador de atividades usando o argumento de linha de comando --config <config> ou --mail-config <config>.

O exemplo a seguir atribui diferentes IDs de conexão a atividades de produtividade específicas (Microsoft Office 365), usando um fallback de curinga:

{
    "* > *": {
        "ConnectionId": "00000000-0000-0000-0000-000000000001"
    },
    "*\\Projects\\MailMigration\\Main.xaml > Get *": {
        "ConnectionId": "00000000-0000-0000-0000-000000000002"
    },
    "*\\Projects\\MailMigration\\* > Send Mail": {
        "ConnectionId": "00000000-0000-0000-0000-000000000003"
    }
}

Neste exemplo:

• * > * corresponde a todas as atividades e atua como um fallback quando não há entradas correspondentes abaixo.
• *\\Projects\\MailMigration\\Main.xaml > Get * corresponde a qualquer atividade cujo nome de exibição comece com Get em Main.xaml.
• *\\Projects\\MailMigration\\* > Send Mail corresponde à atividade Send Mail em todos os fluxos de trabalho na pasta MailMigration.

{
    "* > *": {
        "ConnectionId": "00000000-0000-0000-0000-000000000001"
    },
    "* > [uipath-microsoft-outlook365] *": {
        "ConnectionId": "00000000-0000-0000-0000-000000000002"
    },
    "*\\Projects\\MailMigration\\Main.xaml > [uipath-microsoft-outlook365] Get *": {
        "ConnectionId": "00000000-0000-0000-0000-000000000003"
    }
}

Neste exemplo:

• * > * corresponde a todas as atividades e atua como um fallback quando não há entradas correspondentes abaixo.
• * > [uipath-microsoft-outlook365] * substituições para todas as atividades do Outlook.
• *\\Projects\\MailMigration\\Main.xaml > [uipath-microsoft-outlook365] Get * restringe ainda mais a Get * atividades em um fluxo de trabalho específico.

Configuração de IDs de conexão para atividades do GSuite

As atividades modernas de Connection-Service exigem um ConnectionId que o migrador geralmente não pode inferir. Dois casos:

1. Dentro de um OAuth GSuiteApplicationScope — a atividade herda a conexão do escopo no runtime, então ConnectionId fica vazio (UseConnectionService é definido como false na atividade).
2. Fora de um escopo, OU após um escopo de serviço de conexão ter sido desencapsulado para um Sequence durante a migração — a atividade precisa de um ConnectionId explícito. O migrador não pode gerar um porque o runtime do Studio, não o migrador, é o proprietário do ciclo de vida da conexão IS.

Para desbloquear esse caso, o migrador aceita um arquivo de configuração JSON (--gsuite-config <path>) que mapeia declarativamente instâncias de atividades para valores ConnectionId. O mesmo mecanismo é usado por Email (--mail-config, alias --config).

{
  "{path-to-workflow} > [{connector-type}] {activity-display-name}": {
    "ConnectionId": "00000000-0000-0000-0000-000000000001"
  }
}

No esquema acima, cada regra é um englobamento sobre três coordenadas:

• {path-to-workflow} o caminho do arquivo do fluxo de trabalho (separadores ao estilo do Windows normalizados). * é um curinga.
• [{connector-type}] — opcional A chave do conector IS associada à atividade moderna (por exemplo uipath-google-drive, uipath-google-gmail). Se omitido, a regra corresponderá a qualquer conector.
• {activity-display-name} — o nome de exibição da atividade migrada. * é um curinga.

Quando várias regras correspondem à mesma tupla de fluxo de trabalho + atividade + conector, a última correspondência vence por propriedade, e as propriedades definidas por uma correspondência anterior são preservadas quando não são substituídas — facilitando a camada de um padrão global com substituições por atividade:

{
  "* > *": {
    "ConnectionId": "00000000-0000-0000-0000-000000000001"
  },
  "* > [uipath-google-drive] *": {
    "ConnectionId": "00000000-0000-0000-0000-000000000002"
  },
  "*\\Projects\\Demo\\Main.xaml > [uipath-google-drive] Get *": {
    "ConnectionId": "00000000-0000-0000-0000-000000000003"
  },
  "* > [uipath-google-sheets] *": {
    "ConnectionId": "00000000-0000-0000-0000-000000000004"
  },
  "* > [uipath-google-docs] *": {
    "ConnectionId": "00000000-0000-0000-0000-000000000005"
  },
  "* > [uipath-google-gmail] *": {
    "ConnectionId": "00000000-0000-0000-0000-000000000006"
  }
}

O exemplo acima também configura diferentes IDs de conexão para diferentes serviços do Google Workspace (Drive, Sheets, Docs, Gmail).

ConnectionId é a única propriedade que a configuração pode preencher. Quando um ConnectionId é necessário, mas nenhuma regra corresponde, o migrador emite uma ação necessária apontando o usuário de volta para o arquivo de configuração.

Comportamento do escopo do aplicativo UI Automation após migração

A maioria das atividades modernas de UI Automation requer um escopo de aplicativo (atividade Use Application/Browser).Durante a migração, dois tipos de escopos são criados:

Escopos criados organicamente

Esses escopos são gerados automaticamente ao migrar atividades com escopo clássicas, como Abrir navegador e Anexar navegador. Esses escopos não são otimizados para evitar alterar a intenção e o fluxo originais do fluxo de trabalho migrado.

Escopos gerados sinteticamente

Geramos esses escopos para garantir que o fluxo de trabalho seja compilado e executado corretamente após a migração. Quando dois escopos consecutivos têm propriedades idênticas (por exemplo, o mesmo seletor ou mecanismo de OCR), eles são mesclados em um único escopo enquanto preservam a ordem original da atividade.

Limitações

Atividades do UIAutomation

• A versão de destino mínima compatível de UiPath.UIAutomation.Activities é 25.10.21.
• Algumas propriedades de atividades têm limitações de migração. Veja as listas de atividades compatíveis:
  • Atividades do UI Automation compatíveis
  • Atividades do UI Automation não compatíveis
• Os fluxos de trabalho migrados que usam atividades modernas de UI Automation podem ser executados mais lentamente do que os fluxos de trabalho originais que usam atividades clássicas de UI Automation.

Atividades de produtividade

• A versão de destino mínima compatível de UiPath.MicrosoftOffice365.Activities é 3.6.10.
• Veja as listas de atividades compatíveis:
  • Atividades de email compatíveis
  • Atividades de email não compatíveis

Limitações da ferramenta

• Por padrão, a ferramenta de migração de atividades usa feeds NuGet configurados em NuGet.config: Official, Local e Marketplace. Para incluir feeds de bibliotecas do Orchestrator, use as opções para os comandos analyze, upgrade e bulk: --orchestrator-url, --orchestrator-tenant, --orchestrator-pat, --orchestrator-application-id e --orchestrator-application-secret.
• As atividades que usam tipos ou assemblies gerados dinamicamente (por exemplo, algumas atividades do Excel podem ter nomes de colunas como propriedades em um tipo gerado dinamicamente) podem causar um erro Type not found em arquivos .xaml após a migração.

Regra do Analisador de Fluxo de Trabalho do Studio

• A regra do Analisador de Fluxo de Trabalho ST-AMG-001 está disponível a partir do Studio 2024.10.25 LTS, Studio 2025.10.8 LTS e Studio 2026.0.189 STS.

Melhores práticas de migração

Antes da migração

1. Faça backup de seus projetos: sempre crie um backup completo antes de executar quaisquer comandos de migração.
2. Atualize os pacotes do Studio e de atividades: use a versão mais recente do UiPath Studio e certifique-se de que as versões de pacotes de destino atendam aos requisitos mínimos (UiPath.UIAutomation.Activities >= 25.10.21 e UiPath.MicrosoftOffice365.Activities >= 3.6.10).
3. Analise antes de atualizar: execute primeiro o comando analyze. Use UiPath.Upgrade.exe analyze -p -v para gerar um relatório SARIF e identificar possíveis problemas sem modificar o projeto.
4. Verificar dependências e feeds do NuGet: confirme se os feeds Oficial, Local e Marketplace estão configurados corretamente em NuGet.config.
5. Migre as bibliotecas primeiro quando um projeto depende de projetos de bibliotecas: somente depois migre os projetos que as consomem.

Durante a migração

5. Comece com um único projeto: teste a migração em um projeto usando UiPath.Upgrade.exe upgrade -p -v antes de executar uma operação em massa.
6. Use a migração em massa para vários projetos: uma vez validado, execute UiPath.Upgrade.exe bulk -p -v. Certifique-se de que a estrutura das pastas esteja limpa e consistente.
7. Forneça um arquivo de configuração para IDs de conexão: para atividades do Microsoft 365 ou do GSuite, crie um arquivo de configuração com os valores ConnectionId necessários e o transmita a --config:

{
    "* > *": {
        "ConnectionId": "00000000-0000-0000-0000-000000000001"
    }
}

Após a migração

8. Revise o relatório do SARIF: verifique a pasta .upgrade no diretório do projeto e resolva quaisquer problemas sinalizados.
9. Abra o projeto migrado no Studio e execute Analisar Projeto: revise os resultados da regra ST-AMG-001 do Analisador de Fluxo de Trabalho (disponível no Studio 2025.10.8 Suporte em Longo Prazo/ Studio 2026.0.189 STS ou superior) para identificar atividades que exigem ações pós-migração.
10. Validar escopos de aplicativo: confirme que os escopos mesclados comportam-se conforme o esperado. Teste fluxos de trabalho com atividades Use Application/Browser.
11. Executar testes de ponta a ponta: execute fluxos de trabalho migrados em um ambiente controlado antes de implantar na produção.

Desempenho e manutenção

12. Otimizar seletores de UI Automation: após a migração, revise os seletores para obter precisão e estabilidade.
13. Monitorar período de execução: as atividades modernas podem ser executadas mais lentamente no início. Otimize onde necessário.
14. Documentar suas alterações: mantenha um registro de projetos migrados, versões de destino e configurações aplicadas para fins de auditoria e reversão.