Como fazer: gerenciar recursos do Orchestrator

Daily tasks for managing Orchestrator runtime resources with `uip or`, covering assets, buckets, libraries, queues, triggers, and webhooks.

uip or is the general-purpose CRUD surface over Orchestrator's runtime resources: assets, buckets (and files inside them), libraries, queues (and items), triggers, and webhooks — alongside the jobs, processes, and folders commands documented elsewhere in this guide. This page collects the tasks that come up daily — bulk-creating assets, moving files in and out of buckets, dispatching queue work, inspecting triggers — as copy-pasteable snippets.

The full flag list for every subcommand is on the uip or reference page and its per-resource pages. This page covers the common usage patterns.

Observação:

uip or (this page) is different from uip solution resource. uip or always calls Orchestrator on a live tenant. uip solution resource only ever reads local resource declarations inside a .uipx solution on disk. If in doubt, look at the prefix.

Convenções que você precisa conhecer primeiro

Antes que qualquer fragmento funcione:

• Authentication. Every uip or verb calls Orchestrator. Run uip login first. Run uip login tenant set <name> to switch the active tenant before a call that targets a different one.
• Folder scoping. Assets, buckets, queues, queue items, and time/queue triggers are folder-scoped — pass --folder-path (e.g. Shared) or --folder-key (GUID), or --all-folders where that flag is supported. Libraries, API triggers, and webhooks are tenant-scoped and reject the folder flags.
• Chaves. Listar GUIDs de retorno de verbos (key, identifier, uniqueKey). Passe-os para get, update e delete. Os campos numéricos id são internos; não os passe para comandos.
• Destructive operations require -y, --yes. Every delete verb on these resources refuses to run without it — the CLI never prompts interactively.
• JSON é a saída padrão. Cada fragmento abaixo depende disso; consulte Formatos de saída.

Ativos

Implantar ativos em massa a partir de um CSV

Essa é a tarefa mais comum "gerenciar meus segredos e configuração". Dado um CSV como:

name,value,type,folderPath
ApiEndpoint,https://api.example.com,Text,Shared
MaxRetries,3,Integer,Shared
Debug,false,Bool,Shared

Faça loop sobre ele com bash simples + uip or assets create:

#!/usr/bin/env bash
set -euo pipefail

# Skip the header row
tail -n +2 ./assets.csv | while IFS=, read -r name value type folder; do
  uip or assets create "$name" "$value" \
    --folder-path "$folder" \
    --type "$type"
done

Uma nova execução na mesma pasta falhará em duplicatas. Duas maneiras de lidar com isso:

• Padrão de upsert. Listar primeiro, depois create ou update por linha:

  tail -n +2 ./assets.csv | while IFS=, read -r name value type folder; do
    existing=$(uip or assets list --folder-path "$folder" --name "$name" \
      --output-filter "Data[?name=='$name'] | [0].key" --output plain)
  
    if [ -n "$existing" ] && [ "$existing" != "null" ]; then
      uip or assets update "$existing" "$value"
    else
      uip or assets create "$name" "$value" --folder-path "$folder" --type "$type"
    fi
  done
  

• Padrão de implantação da solução. Para conjuntos de ativos que são enviados junto com um pacote, declare-os no manifesto da solução e use uip solution deploy run --config-file — esse caminho é idempotente por design. Consulte Como fazer: empacotar e publicar uma solução.

Ativos do tipo Credential

Os ativos Credential e Secret precisam de uma chave de armazenamento de credenciais:

# Find the credential store
STORE_KEY=$(uip or credential-stores list \
  --output-filter "Data[?name=='MyStore'] | [0].key" --output plain)

# Create the credential asset (value format: username:password)
uip or assets create ApiLogin "alice:s3cr3t" \
  --folder-path Shared \
  --type Credential \
  --credential-store-key "$STORE_KEY"

Os valores de credencial e segredo nunca são retornados por list ou get; use assets get-asset-value (que ainda precisa de um escopo de pasta) para ler o valor dinâmico ou chame por meio do robô.

Compartilhamento de ativos entre pastas

Crie uma vez em Shared e, em seguida, compartilhe para cada pasta que precisar dele:

ASSET_KEY=$(uip or assets list --folder-path Shared --name ApiEndpoint \
  --output-filter "Data[0].key" --output plain)

for folder in Production Staging Development; do
  uip or assets share "$ASSET_KEY" --folder-path "$folder"
done

Revogar com unshare. Consulte Ativos para obter a lista completa de verbos.

Buckets e arquivos de bucket

Carregar um arquivo local

BUCKET_KEY=$(uip or buckets list --folder-path Shared \
  --output-filter "Data[?name=='invoices'] | [0].key" --output plain)

uip or bucket-files upload "$BUCKET_KEY" "inbox/invoice-001.pdf" \
  --folder-path Shared \
  --file ./invoice-001.pdf

O caminho dentro do bucket (inbox/invoice-001.pdf) é o segundo argumento para upload; --file é o caminho local a ser carregado. O tipo de conteúdo é detectado automaticamente; passe --content-type para substituir.

Baixar um arquivo

uip or bucket-files download "$BUCKET_KEY" "reports/summary.csv" \
  --folder-path Shared \
  --destination ./summary.csv

--destination, o conteúdo é transmitido para stdout — útil para pipeline em um processador.

Listar e paginar

# First page
uip or bucket-files list "$BUCKET_KEY" --folder-path Shared

# The response carries a continuationToken — pass it back to fetch the next page
uip or bucket-files list "$BUCKET_KEY" --folder-path Shared \
  --continuation-token "<token-from-previous-response>"

As listagens de arquivos do bucket são o único recurso na CLI que usa um token de continuação em vez da paginação de deslocamento — os outros verbos da lista levam --limit / --offset.

URLs pré-assinados

Se um robô ou serviço externo precisar de acesso direto ao blob sem passar pela CLI:

uip or bucket-files get-upload-url "$BUCKET_KEY" "inbox/incoming.pdf" \
  --folder-path Shared --expiry-in-minutes 30

uip or bucket-files get-download-url "$BUCKET_KEY" "reports/summary.csv" \
  --folder-path Shared --expiry-in-minutes 30

Ambos retornam um URL com limite de tempo definido para o caminho do arquivo único.

Filas e itens de filas

Crie uma fila

uip or queues create InvoiceQueue \
  --folder-path Shared \
  --max-retries 3 \
  --retention-period 90

Lista completa de sinalizadores — --auto-retry, --enforce-unique-reference, --encrypted, configurações de retenção — na referência de filas.

Adicionar um único item de trabalho

uip or queue-items add InvoiceQueue \
  --folder-path Shared \
  --specific-content '{"InvoiceId":"INV-001","Amount":1500}' \
  --priority High

--specific-content a carga do JSON que o robô lerá.

Adicionar de um arquivo em massa

cat > ./items.json <<'EOF'
[
  {"specificContent": {"InvoiceId":"INV-001"}, "priority": "Normal"},
  {"specificContent": {"InvoiceId":"INV-002"}, "priority": "Normal"}
]
EOF

ITEMS=$(jq -c . ./items.json)
uip or queue-items bulk-add InvoiceQueue \
  --folder-path Shared \
  --queue-items "$ITEMS" \
  --commit-type StopOnFirstFailure

Each item accepts specificContent, priority, reference, deferDate, dueDate — there is no per-item queue name; the queue is the single positional argument (InvoiceQueue above) shared by the whole batch.

--commit-type controla o que acontece quando uma linha falha na validação: ProcessAllIndependently (padrão), StopOnFirstFailure ou AllOrNothing.

Inspecionar itens com falha

uip or queue-items list --folder-path Shared \
  --queue-name InvoiceQueue \
  --status Failed \
  --output-filter "Data[].{key:uniqueKey, ref:reference, reason:processingException}"

Use queue-items get-history em um único uniqueKey para ver seu histórico de transição de estado completo — útil para diagnosticar loops de nova tentativa.

Marcar itens com falha para nova tentativa

uip or queue-items set-review-status Retried \
  "<queue-item-key-1>" "<queue-item-key-2>"

set-review-status fica com um dos Retried, Abandoned, Deleted.

Gatilhos

Listar gatilhos em uma pasta

uip or triggers list --type time --folder-path Shared --enabled \
  --output-filter "Data[].{name:name, cron:startProcessCron, enabled:isEnabled}"

Três tipos de gatilho: time, queue e api. Passe --type em cada verbo (ele volta para time). Os gatilhos de API têm o escopo de tenant — omita --folder-path.

Criar um gatilho de tempo

RELEASE_KEY=$(uip or processes list --folder-path Shared --name InvoiceProcessing \
  --output-filter "Data[0].Key" --output plain)

uip or triggers create --type time \
  --name NightlyInvoices \
  --release-key "$RELEASE_KEY" \
  --runtime-type Unattended \
  --job-priority Normal \
  --folder-path Shared \
  --cron "0 0 2 * * ?" \
  --time-zone UTC

O valor --cron usa o formato de 6 campos do Quartz (sec min hour dayOfMonth month dayOfWeek), não o cron padrão. "0 0 2 * * ?" é "todos os dias às 02:00".

Habilitar ou desabilitar um gatilho

There is no dedicated enable/disable command — toggle a trigger through update:

uip or triggers update <trigger-key> --type time --folder-path Shared --disabled
uip or triggers update <trigger-key> --type time --folder-path Shared --enabled

Use triggers history para diagnosticar um gatilho que não está disparando — o log de disparo revela licenças ausentes, máquinas indisponíveis e outros blocos upstream.

Webhooks

Os webhooks têm o escopo de tenant. Crie uma vez e o webhook é acionado em cada evento correspondente no tenant:

uip or webhooks create JobAlerts \
  --url https://hooks.example.com/uipath \
  --events "job.completed,job.faulted" \
  --secret "$WEBHOOK_SECRET"

Liste os tipos de eventos disponíveis para um tenant:

uip or webhooks event-types

Teste a entrega sem esperar um evento real:

uip or webhooks ping <webhook-key>

Bibliotecas

As bibliotecas têm o escopo de tenant (não de pasta) — elas residem no feed do tenant e são referenciadas por IDs de pacote como MyLib:1.0.0:

# Upload a new version
uip or libraries upload --file ./MyLib.1.0.0.nupkg

# See all versions of a package
uip or libraries versions MyLib

# Download a specific version
uip or libraries download MyLib:1.0.0 --destination ./MyLib.1.0.0.nupkg

As chaves assumem a forma PackageId:Version — não um GUID.

Dicas de script

• Sempre passe --output-filter ao fornecer um único valor a uma variável. Evita invocações frágeis jq e valida no tempo de análise CLI — consulte Padrões de script.
• Os verbos de lista retornam resultados paginados — --limit / --offset no máximo, --continuation-token em arquivos do bucket. Resultados vazios (zeras linhas em Data) ainda saem de 0 — a consulta da lista foi bem-sucedida; não há correspondências.
• A maioria dos verbos de atualização/exclusão é entre pastas — a tabela de sinalizadores na seção de cada verbo de uip or diz isso explicitamente ("Pasta cruzada"). Apenas create e lista precisam do escopo da pasta nesses recursos.

Veja também

• Referênciauip or — a lista autorizativa de sinalizadores verbo por verbo. Cada fragmento nessa página tem links de volta para a seção de correspondência.
• uip solution deploy config link — associe o recurso declarado de uma Solução a um que você criou com uip or.
• Padrões de script — pesquisa, nova tentativa na saída 2, pipelines idempotentes.
• Como fazer: empacotar e publicar uma Solução — o caminho alternativo para recursos que são fornecidos com um pacote.