Tutorial: gestionar los recursos de Orchestrator

Tareas diarias para gestionar los recursos de runtime de Orchestrator con `uip o`, que cubren activos, depósitos, bibliotecas, colas, desencadenadores y webhooks.

uip or es la superficie CRUD de propósito general sobre los recursos de runtime de Orchestrator: activos, depósitos (y archivos en su interior), bibliotecas, colas (y elementos), desencadenadores y webhooks , junto con los comandos de trabajos, procesos y carpetas documentados en otro lugar de esta guía. Esta página recopila las tareas que surgen a diario (crear activos en masa, mover archivos dentro y fuera de los depósitos, enviar trabajo en cola, inspeccionar desencadenadores) como fragmentos que se pueden copiar y pegar.

La lista completa de marcadores para cada subcomando está en la página de referencia uip or y sus páginas por recurso. Esta página cubre los patrones de uso comunes.

Nota:

uip or (esta página) es diferente de uip solution resource. uip or siempre llama a Orchestrator en un tenant activo. uip solution resource solo lee las declaraciones de recursos locales dentro de una solución .uipx en el disco. En caso de duda, consulta el prefijo.

Convenciones que debe conocer primero

Antes de que funcione cualquier fragmento:

• Autenticación. Cada verbo uip or llama a Orchestrator. Ejecuta uip login primero. Ejecuta uip login tenant set <name> para cambiar el tenant activo antes de una llamada dirigida a uno diferente.
• Ámbito de carpeta. Los activos, depósitos, colas, artículos en cola y desencadenadores de tiempo/cola tienen ámbito de carpeta : pase --folder-path (por ejemplo Shared) o --folder-key (GUID), o --all-folders donde se admite ese marcador. Las bibliotecas, los desencadenadores de API y los webhooks tienen ámbito de tenant y rechazan los marcadores de carpeta.
• Claves. Enumerar verbos devuelve GUID (key, identifier, uniqueKey). Pásalas a get, update y delete. Los campos numéricos id son internos; no los pases a los comandos.
• Las operaciones destructivas requieren -y, --yes. Cada verbo delete en estos recursos se niega a ejecutarse sin él: la CLI nunca solicita de forma interactiva.
• JSON es la salida predeterminada. Cada fragmento a continuación se basa en esto; consulta Formatos de salida.

Activos

Implementación masiva de activos desde un CSV

Esta es la tarea más común de "gestionar mis secretos y configuración". Dado un CSV como:

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

Repite con bash simple + 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

Volver a ejecutar esto en la misma carpeta fallará en los duplicados. Dos formas de manejar eso:

• Patrón de upsert. Enumerar primero, luego create o update por fila:

  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
  

• Patrón de implementación de la solución. Para los conjuntos de activos que se envían junto con un paquete, decláralos en el manifiesto de la solución y utiliza uip solution deploy run --config-file : esa ruta es idempotente por diseño. Consulta Tutorial: empaquetar y publicar una solución.

Activos de tipo credencial

Los activos de credenciales y secretos necesitan una clave de almacén de credenciales:

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

Los valores de credencial y secreto nunca son devueltos por list o get; utiliza assets get-asset-value (que aún necesita un ámbito de carpeta) para leer el valor activo o llamar a través del robot.

Compartir activos entre carpetas

Crear una vez en Shared luego compartir con cada carpeta que lo necesite:

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

Revocar con unshare. Consulta Activos para ver la lista completa de verbos.

Depósitos y archivos de depósito

Cargar un archivo 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

La ruta dentro del depósito (inbox/invoice-001.pdf) es el segundo argumento de upload; --file es la ruta local para cargar. El tipo de contenido se detecta automáticamente; pasa --content-type para anular.

Descargar un archivo

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

Sin --destination, el contenido se transmite a stdout, útil para canalizar a un procesador.

Enumerar y 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>"

Los listados de archivos de depósito son el único recurso en la CLI que utiliza un token de continuación en lugar de paginación de desplazamiento: los otros verbos de lista toman --limit / --offset.

URL prefirmadas

Si un robot o servicio externo necesita acceso directo a blob sin pasar por la 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 devuelven una URL de tiempo limitado en el ámbito de la ruta de archivo única.

Colas y artículos en cola

Crear una cola

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

Lista completa de marcadores ( --auto-retry, --enforce-unique-reference, --encrypted, configuración de retención) en la referencia de colas.

Añadir un único elemento de trabajo

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

--specific-content es la carga útil JSON que leerá el robot.

Añadir en masa desde un archivo

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

Cada elemento acepta specificContent, priority, reference, deferDate, dueDate — no hay nombre de cola por elemento; la cola es el único argumento posicional (InvoiceQueue arriba) compartido por todo el lote.

--commit-type controla lo que sucede cuando una fila falla en la validación: ProcessAllIndependently (predeterminado), StopOnFirstFailure o AllOrNothing.

Inspeccionar elementos fallidos

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

Usa queue-items get-history en un solo uniqueKey para ver su historial completo de transición de estado, útil para diagnosticar bucles de reintento.

Marcar elementos fallidos para reintentar

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

set-review-status toma uno de Retried, Abandoned, Deleted.

Desencadenadores

Enumerar desencadenadores en una carpeta

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

Tres tipos de desencadenador: time, queue y api. Transfiera --type en cada verbo (el valor predeterminado es time). Los desencadenadores de API tienen ámbito de tenant: omite --folder-path.

Crear un desencadenador de tiempo

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

El valor --cron utiliza el formato de 6 campos de Quartz (sec min hour dayOfMonth month dayOfWeek), no el cron estándar. "0 0 2 * * ?" es "todos los días a las 02:00".

Habilitar o deshabilitar un desencadenador

No hay un comando enable/disable dedicado — alterna un desencadenador a través de 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

Usa triggers history para diagnosticar un desencadenador que no se activa: el registro de activación muestra licencias faltantes, máquinas no disponibles y otros bloqueos ascendentes.

Webhooks

Los webhooks tienen ámbito de tenant. Crea una vez y el webhook se activa en cada evento coincidente en el tenant:

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

Enumera los tipos de eventos disponibles para un tenant:

uip or webhooks event-types

Prueba la entrega sin esperar un evento real:

uip or webhooks ping <webhook-key>

Librerías

Las bibliotecas tienen ámbito de tenant (no de carpeta): residen en la fuente del tenant y se referencian mediante ID de paquete 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

Las claves toman la forma PackageId:Version , no un GUID.

Consejos de scripting

• Omita siempre --output-filter al introducir un único valor en una variable. Evita las invocaciones jq frágiles y se valida en tiempo de análisis de CLI: consulta Patrones de scripting.
• Los verbos de lista devuelven resultados paginados : --limit / --offset en la mayoría, --continuation-token en los archivos de depósito. Los resultados vacíos (cero filas en Data) siguen saliendo 0 : la consulta de la lista se realizó correctamente; nada coincide.
• La mayoría de los verbos de actualización/eliminación son multicarpeta : la tabla de marcas en la sección de cada verbo de uip or lo dice explícitamente ("Carpeta cruzada"). Solo create y la lista necesitan el ámbito de la carpeta en esos recursos.

Ver también

• Referenciauip or : la lista de marcadores autorizada verbo por verbo. Cada fragmento de esta página se vincula a la sección correspondiente.
• uip solution deploy config link : vincula el recurso declarado de una solución a uno que creaste con uip or.
• Patrones de scripting : sondeo, reintentar en la salida 2, procesos idempotentes.
• Tutorial: empaquetar y publicar una solución : la ruta alternativa para los recursos que se envían con un paquete.