@uipath/skills 1.195.0

package/skills/uipath-rpa/references/legacy/data-manipulation-guide.md

@@ -0,0 +1,390 @@
+# Data Manipulation Guide
+
+Advanced data manipulation patterns for legacy UiPath workflows: RegEx, LINQ, JObject, StringBuilder, and type conversion edge cases.
+
+For basic VB.NET expressions (strings, DataTable access, DateTime, collections), see [activity-docs/_PATTERNS.md](./activity-docs/_PATTERNS.md).
+
+---
+
+## 1. Regular Expressions (RegEx)
+
+Use `System.Text.RegularExpressions.Regex` for pattern matching and extraction. Available by default in legacy projects.
+
+### Common Patterns
+
+| Pattern | RegEx | Match Examples |
+|---|---|---|
+| Email | `[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}` | `user@example.com` |
+| Phone (US) | `\(?\d{3}\)?[-.\s]?\d{3}[-.\s]?\d{4}` | `(555) 123-4567`, `555.123.4567` |
+| Date (MM/DD/YYYY) | `\d{2}/\d{2}/\d{4}` | `01/15/2025` |
+| Date (YYYY-MM-DD) | `\d{4}-\d{2}-\d{2}` | `2025-01-15` |
+| Currency (USD) | `\$[\d,]+\.?\d{0,2}` | `$1,234.56`, `$50` |
+| Invoice Number | `INV-\d{4,10}` | `INV-12345`, `INV-0001234567` |
+| ZIP Code (US) | `\d{5}(-\d{4})?` | `90210`, `90210-1234` |
+| SSN | `\d{3}-\d{2}-\d{4}` | `123-45-6789` |
+| IP Address | `\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}` | `192.168.1.1` |
+| Decimal Number | `-?\d+\.?\d*` | `123.45`, `-67`, `0.5` |
+
+### VB.NET Usage
+
+```vb
+' Check if string matches pattern
+System.Text.RegularExpressions.Regex.IsMatch(inputText, "\d{3}-\d{2}-\d{4}")
+
+' Extract first match
+System.Text.RegularExpressions.Regex.Match(inputText, "INV-\d+").Value
+
+' Extract all matches (returns MatchCollection — iterate in ForEach)
+System.Text.RegularExpressions.Regex.Matches(inputText, "\$[\d,]+\.?\d{0,2}")
+
+' Replace matched text
+System.Text.RegularExpressions.Regex.Replace(inputText, "\s+", " ")
+
+' Extract with named groups
+System.Text.RegularExpressions.Regex.Match(inputText, "(?<amount>\$[\d,.]+)\s+(?<date>\d{2}/\d{2}/\d{4})")
+' Access: match.Groups("amount").Value, match.Groups("date").Value
+```
+
+### Rules
+
+1. **Use `Regex.IsMatch` before `Regex.Match`** when you only need a boolean check
+2. **Use named groups `(?<name>...)` for multi-value extraction** — clearer than positional groups
+3. **Escape special characters** — `.` matches any character; use `\.` for literal dot
+4. **Test patterns on sample data first** — regex bugs silently return empty matches
+5. **Set a timeout for complex patterns** — `New Regex(pattern, RegexOptions.None, TimeSpan.FromSeconds(5))` prevents catastrophic backtracking
+
+---
+
+## 2. StringBuilder
+
+Use `System.Text.StringBuilder` when concatenating strings in a loop. Regular `+` concatenation creates a new string object each iteration, wasting memory for large loops.
+
+### When to Use
+
+| Scenario | Use |
+|---|---|
+| Concatenating < 10 strings | Regular `+` or `String.Format` |
+| Building a string in a loop (10+ iterations) | `StringBuilder` |
+| Building large HTML/XML content | `StringBuilder` |
+| Simple single-line concatenation | Regular `+` |
+
+### VB.NET Pattern (InvokeCode)
+
+```vb
+Dim sb As New System.Text.StringBuilder()
+For Each row As DataRow In dt.Rows
+    sb.AppendLine(row("Name").ToString() & "," & row("Amount").ToString())
+Next
+Dim result As String = sb.ToString()
+```
+
+### In Workflow (without InvokeCode)
+
+1. Assign: `sb = New System.Text.StringBuilder()` (variable type: `System.Text.StringBuilder`)
+2. Inside For Each: Assign: `sb.AppendLine(row("Name").ToString())`
+3. After loop: Assign: `result = sb.ToString()`
+
+---
+
+## 3. Advanced LINQ for DataTables
+
+All LINQ operations require `System.Linq` in namespace imports (included by default in legacy projects). DataTable LINQ requires `.AsEnumerable()` first.
+
+### GroupBy
+
+```vb
+' Group rows by department, returns IEnumerable(Of IGrouping)
+dt.AsEnumerable().GroupBy(Function(r) r("Department").ToString())
+
+' Get grouped counts
+dt.AsEnumerable() _
+    .GroupBy(Function(r) r("Department").ToString()) _
+    .Select(Function(g) New Object() {g.Key, g.Count()})
+```
+
+### OrderBy / ThenBy
+
+```vb
+' Single sort
+dt.AsEnumerable() _
+    .OrderBy(Function(r) r("Name").ToString()) _
+    .CopyToDataTable()
+
+' Descending
+dt.AsEnumerable() _
+    .OrderByDescending(Function(r) Convert.ToDouble(r("Amount"))) _
+    .CopyToDataTable()
+
+' Multi-column sort
+dt.AsEnumerable() _
+    .OrderBy(Function(r) r("Department").ToString()) _
+    .ThenByDescending(Function(r) Convert.ToDouble(r("Amount"))) _
+    .CopyToDataTable()
+```
+
+### Aggregations
+
+```vb
+' Sum
+dt.AsEnumerable().Sum(Function(r) Convert.ToDouble(r("Amount")))
+
+' Average
+dt.AsEnumerable().Average(Function(r) Convert.ToDouble(r("Amount")))
+
+' Count with condition
+dt.AsEnumerable().Count(Function(r) r("Status").ToString() = "Active")
+
+' Min / Max
+dt.AsEnumerable().Min(Function(r) Convert.ToDateTime(r("Date")))
+dt.AsEnumerable().Max(Function(r) Convert.ToDouble(r("Amount")))
+```
+
+### Any / All
+
+```vb
+' Check if any row matches
+dt.AsEnumerable().Any(Function(r) Convert.ToDouble(r("Amount")) > 10000)
+
+' Check if all rows match
+dt.AsEnumerable().All(Function(r) Not String.IsNullOrEmpty(r("Email").ToString()))
+```
+
+### Distinct
+
+```vb
+' Distinct values from one column
+dt.AsEnumerable().Select(Function(r) r("Department").ToString()).Distinct().ToArray()
+
+' Distinct rows (by all columns) — use DataRowComparer
+dt.AsEnumerable().Distinct(DataRowComparer.Default).CopyToDataTable()
+```
+
+### Take / Skip (Pagination)
+
+```vb
+' First 10 rows
+dt.AsEnumerable().Take(10).CopyToDataTable()
+
+' Skip first 10, take next 10
+dt.AsEnumerable().Skip(10).Take(10).CopyToDataTable()
+```
+
+### CopyToDataTable Gotcha
+
+`CopyToDataTable()` throws `InvalidOperationException` when the LINQ result is empty. ALWAYS check first:
+
+```vb
+Dim filtered = dt.AsEnumerable().Where(Function(r) r("Status").ToString() = "Active")
+If filtered.Any() Then
+    resultDt = filtered.CopyToDataTable()
+Else
+    resultDt = dt.Clone()  ' Empty DataTable with same structure
+End If
+```
+
+---
+
+## 4. Dictionary Operations
+
+### Common Operations
+
+```vb
+' Check if key exists
+myDict.ContainsKey("KeyName")
+
+' Safe get (avoids KeyNotFoundException)
+Dim value As String = Nothing
+If myDict.TryGetValue("KeyName", value) Then
+    ' Use value
+End If
+
+' Iterate key-value pairs (ForEach with TypeArgument KeyValuePair(Of String, Object))
+For Each kvp As KeyValuePair(Of String, Object) In myDict
+    ' kvp.Key, kvp.Value
+Next
+
+' Get all keys or values
+myDict.Keys.ToList()
+myDict.Values.ToList()
+
+' Merge two dictionaries (second overwrites first on key conflicts)
+For Each kvp In dict2
+    dict1(kvp.Key) = kvp.Value
+Next
+
+' Count
+myDict.Count
+```
+
+### Nested Dictionaries
+
+For Config.xlsx-style hierarchical data:
+
+```vb
+' Dictionary(Of String, Dictionary(Of String, String))
+Dim settings = DirectCast(configDict("DatabaseSettings"), Dictionary(Of String, String))
+Dim connString = settings("ConnectionString")
+```
+
+---
+
+## 5. JObject / JArray (Newtonsoft.Json)
+
+`Newtonsoft.Json` is bundled with UiPath legacy projects. Use `Newtonsoft.Json.Linq` for JSON parsing and manipulation.
+
+### Parsing
+
+```vb
+' Parse JSON string to JObject
+Dim jObj = Newtonsoft.Json.Linq.JObject.Parse(jsonString)
+
+' Parse JSON array
+Dim jArr = Newtonsoft.Json.Linq.JArray.Parse(jsonArrayString)
+```
+
+### Accessing Values
+
+```vb
+' Top-level property
+jObj("name").ToString()
+
+' Nested property
+jObj("address")("city").ToString()
+
+' Array element
+jArr(0)("name").ToString()
+
+' Safe access (returns Nothing if path doesn't exist)
+jObj("optional")?("nested")?.ToString()
+
+' Typed value
+jObj("count").Value(Of Integer)()
+jObj("isActive").Value(Of Boolean)()
+```
+
+### Querying with LINQ to JSON
+
+```vb
+' Select all items matching condition
+jArr.Where(Function(item) item("status").ToString() = "active")
+
+' Select specific field from array
+jArr.Select(Function(item) item("name").ToString()).ToList()
+```
+
+### Creating/Modifying
+
+```vb
+' Create JObject
+Dim jObj = New Newtonsoft.Json.Linq.JObject()
+jObj("name") = "John"
+jObj("age") = 30
+
+' Serialize back to string
+Dim jsonString = jObj.ToString()
+' Or compact: Newtonsoft.Json.JsonConvert.SerializeObject(jObj)
+```
+
+### API Response Pattern
+
+```vb
+' HTTP Request → responseBody (String)
+' Parse response
+Dim response = Newtonsoft.Json.Linq.JObject.Parse(responseBody)
+
+' Check for errors
+If response("error") IsNot Nothing Then
+    Throw New BusinessRuleException("API error: " & response("error")("message").ToString())
+End If
+
+' Extract data
+Dim items = DirectCast(response("data")("items"), Newtonsoft.Json.Linq.JArray)
+For Each item In items
+    ' Process item("id").ToString(), item("name").ToString()
+Next
+```
+
+---
+
+## 6. Null Safety Patterns
+
+### String Null Checks
+
+```vb
+' Check for null or empty
+String.IsNullOrEmpty(myVar)
+
+' Check for null, empty, or whitespace-only
+String.IsNullOrWhiteSpace(myVar)
+
+' Null coalesce (return default if null)
+If(myVar Is Nothing, "default", myVar.ToString())
+If(String.IsNullOrEmpty(myVar), "default", myVar)
+```
+
+### DataRow Null Checks
+
+```vb
+' Cell may be DBNull (not Nothing)
+If row("Column") Is DBNull.Value OrElse row("Column") Is Nothing Then
+    ' Handle missing value
+Else
+    Dim value = row("Column").ToString()
+End If
+
+' Compact check
+If(IsDBNull(row("Column")), "default", row("Column").ToString())
+```
+
+### Object/Generic Null Checks
+
+```vb
+' Check Nothing
+If myObject Is Nothing Then ...
+
+' Safe ToString
+If(myObject Is Nothing, "", myObject.ToString())
+
+' Type check before cast
+If TypeOf myObject Is DataTable Then
+    Dim dt = DirectCast(myObject, DataTable)
+End If
+```
+
+---
+
+## 7. Type Conversion Edge Cases
+
+### Integer Parsing
+
+| Method | Behavior on Failure | Use When |
+|---|---|---|
+| `CInt(value)` | Throws `InvalidCastException` | VB.NET shorthand, known-good data |
+| `Convert.ToInt32(value)` | Throws `FormatException` | .NET standard, handles null (returns 0) |
+| `Integer.Parse(value)` | Throws `FormatException` | Explicit intent, known-good data |
+| `Int32.TryParse(value, result)` | Returns `False`, sets result to 0 | **SAFEST** — use for external/user input |
+
+### Culture-Dependent Parsing
+
+Number and date formats differ by culture. **ALWAYS specify culture for external data:**
+
+```vb
+' DANGEROUS: depends on system locale
+CDbl("1,234.56")   ' Works on US locale, fails on German locale (1.234,56)
+
+' SAFE: explicit culture
+Double.Parse("1,234.56", System.Globalization.CultureInfo.InvariantCulture)
+
+' SAFE: explicit date format
+DateTime.ParseExact("01/15/2025", "MM/dd/yyyy", System.Globalization.CultureInfo.InvariantCulture)
+```
+
+### Common Conversion Traps
+
+| Trap | Issue | Fix |
+|---|---|---|
+| `CInt("12.5")` | Rounds to 12 (not truncates) | Use `CInt(Math.Floor(CDbl("12.5")))` for truncation |
+| `CDate("01/02/2025")` | Jan 2 or Feb 1? Depends on locale | Use `DateTime.ParseExact` with explicit format |
+| `CBool("yes")` | Throws — only `"True"`/`"False"` work | Use `If(value.ToLower() = "yes", True, False)` |
+| `GenericValue("10") > GenericValue("9")` | Returns `False` — string comparison | Cast to `Int32` first: `CInt(gv1) > CInt(gv2)` |
+| `Convert.ToInt32(Nothing)` | Returns 0 (not exception) | Check for Nothing first if 0 is a valid value |

package/skills/uipath-rpa/references/legacy/discovery-workflow.md

@@ -0,0 +1,147 @@
+# Discovery Workflow — Detailed Steps
+
+Complete discovery procedure before writing or editing any XAML. Referenced from the main skill when detailed guidance is needed.
+
+---
+
+## Step 1: Project Structure
+
+```
+Glob: pattern="**/*.xaml" path="{projectRoot}"       → list all XAML workflow files
+Read: file_path="{projectRoot}/project.json"          → read the project definition
+```
+
+Analyze: folder conventions, naming patterns, existing workflows, `expressionLanguage` (VB.NET or C#), installed packages (`dependencies`).
+
+---
+
+## Step 2: Consult Activity Reference Docs
+
+Read `references/activity-docs/` for behavioral context (what activities do, gotchas, patterns).
+
+| Situation | Action |
+|-----------|--------|
+| Know the package | Read `activity-docs/{PackageName}.md` directly |
+| Don't know the package | Read `activity-docs/_INDEX.md` to find it |
+| Need VB.NET expressions | Read `activity-docs/_PATTERNS.md` |
+| Need XAML structure | Read `references/xaml-basics-and-rules.md` |
+| Need gotchas | Read `activity-docs/_COMMON-PITFALLS.md` |
+| Need InvokeCode patterns | Read `activity-docs/_INVOKE-CODE.md` |
+| Working with REFramework | Read `activity-docs/_REFRAMEWORK.md` |
+| Working with Document Understanding | Read `activity-docs/_DU-PROCESS.md` |
+| Need all activities | Read `activity-docs/AllActivities.md` |
+
+**These docs tell you what and how — NOT exact CLR property names/enum values for XAML. Steps 4 and 5 are mandatory for that.**
+
+---
+
+## Step 3: Search Current Project
+
+```
+Glob: pattern="**/*pattern*.xaml" path="{projectRoot}"
+Grep: pattern="ActivityName|pattern" path="{projectRoot}"
+Read: file_path="{projectRoot}/ExistingWorkflow.xaml"
+```
+
+Mature project: prioritize local patterns. Greenfield: skip.
+
+---
+
+## Step 4: Discover Activities (MANDATORY for non-built-in activities)
+
+**Skip find-activities for built-in activities** listed in [_BUILT-IN-ACTIVITIES.md](./activity-docs/_BUILT-IN-ACTIVITIES.md): If, Assign, Sequence, TryCatch, Flowchart, ForEach, While, Switch, Throw, Delay, Parallel, LogMessage, InvokeCode, InvokeWorkflowFile, ForEachRow, AddDataRow. Use the provided XAML snippets directly.
+
+**For all other activities**, run find-activities. Returns exact class names, argument signatures, types, **ready-to-use XAML snippet**, and **xmlns declaration**.
+
+```bash
+uip rpa-legacy find-activities "{projectRoot}" --query "send mail" --output json
+uip rpa-legacy find-activities "{projectRoot}" --query "invoke code" --include-type-definitions --output json
+```
+
+**Use the returned `XamlSnippet` as your starting point** for activity XAML — it has correct element names, namespaces, and property names for the installed package version. Also add the returned `XmlnsDeclaration` to the root `<Activity>` element.
+
+**Query syntax tips:**
+- **Multi-word queries work** with relevance scoring: `"Excel Read Range"` splits into words, scores matches, bonuses when all words match
+- **CamelCase boundaries detected**: `"SendHotkey"`, `"ExcelReadRange"` match correctly
+- **Use `--exact`** when you know the exact activity name: `--query "ReadRange" --exact` — avoids irrelevant results
+- Each call takes ~15-30 seconds — use `--exact` for known names to get precise results fast
+- If a query returns too many irrelevant results, add `--exact` or use more specific terms
+
+Activity reference docs describe behavior/gotchas but NOT exact CLR class names or argument types. Skipping this step → guessing → wasted validation cycles.
+
+---
+
+## Step 5: Inspect Types (MANDATORY for Enums/Complex Types)
+
+**Run for every enum or complex type.** Gets exact valid values.
+
+```bash
+# Example: InvokeCode Language accepts VBNet and CSharp (NOT "VisualBasic" or "VB")
+uip rpa-legacy type-definition "{projectRoot}" --type "NetLanguage" --output json
+
+uip rpa-legacy type-definition "{projectRoot}" --type "System.Net.Mail.MailMessage" --output json
+```
+
+When to run: any enum property, any complex type argument, any type without listed valid values in docs.
+
+---
+
+## Step 5.5: Search NuGet for Packages (When Needed)
+
+When the known packages in [project-structure.md](./project-structure.md) and `find-activities` don't cover a capability:
+
+```bash
+uip rpa-legacy find-package --query "barcode" --limit 10 --output json
+```
+
+Searches all configured NuGet feeds by name and description. After finding the right package, add it to `dependencies` in project.json, then `find-activities` will index its activities.
+
+Also works for arbitrary .NET packages (e.g., `CsvHelper`, `HtmlAgilityPack`). Avoid packages already bundled with Studio (e.g., `Newtonsoft.Json`) — version conflicts can cause issues.
+
+---
+
+## Step 6: Search UiPath Documentation (Fallback)
+
+```bash
+uip docsai ask "best practices for Excel automation in legacy projects" --output json
+uip docsai ask "ExcelApplicationScope ActivityAction body validation error" --output json
+```
+
+Use when: bundled docs + CLI tools don't cover the topic, need best practices/guidelines/troubleshooting, unfamiliar error, platform concepts (Orchestrator, queues, triggers).
+
+---
+
+## Step 7: Search the Web (Last Resort)
+
+Use `WebSearch` for UiPath Forum, Stack Overflow, GitHub, Reddit:
+
+```
+WebSearch: "UiPath forum ExcelApplicationScope ActivityAction body legacy"
+WebSearch: "site:stackoverflow.com UiPath legacy ExcelApplicationScope XAML"
+WebSearch: "site:github.com UiPath REFramework legacy XAML example"
+```
+
+Use when: all previous steps fail, obscure errors, community workarounds needed. Always verify web-sourced info against project config.
+
+---
+
+## Troubleshooting
+
+### Wrong enum value
+**Symptom:** "Cannot create unknown type" or "is not a member of"
+**Fix:** `uip rpa-legacy type-definition "{projectRoot}" --type "EnumTypeName" --output json`
+
+### Activity class name not found
+**Symptom:** Unknown activity type or missing namespace
+**Fix:** `uip rpa-legacy find-activities "{projectRoot}" --query "..." --output json`, add xmlns + assembly ref
+
+### Multiple errors after batch editing
+**Symptom:** Many errors at once
+**Fix:** Revert to last good state. Re-add one activity at a time, validating after each.
+
+### Activity docs don't match XAML property names
+**Symptom:** Properties from docs don't work
+**Fix:** `find-activities --include-type-definitions` for exact CLR property names
+
+### Stuck on unfamiliar problem
+**Escalation:** `docsai ask` → `WebSearch` → ask user

package/skills/uipath-rpa/references/legacy/environment-setup.md

@@ -0,0 +1,78 @@
+# Phase 0: Environment Readiness
+
+**Goal:** Establish the project root and verify the project is a legacy framework project before any other operations.
+
+**Key difference from modern (`uip rpa`):** The `uip rpa-legacy` CLI is standalone — it does **not** require Studio Desktop to be running. It resolves dependencies from NuGet directly and uses UiRobot for execution.
+
+---
+
+## Step 0.1: Establish Project Root
+
+All `uip rpa-legacy` commands require a `<project-path>` argument pointing to the folder containing `project.json` (or the `project.json` file itself).
+
+```bash
+# Check if project.json exists in the CWD
+ls {cwd}/project.json
+```
+
+If the CWD is not the project root:
+- Locate the project root by finding `project.json`: `Glob: pattern="**/project.json"`
+- Ask the user where their project is located if multiple `project.json` files are found
+
+Store the project root path and use it consistently as `{projectRoot}` throughout all subsequent operations.
+
+---
+
+## Step 0.2: Verify Legacy Project
+
+Read `project.json` and confirm this is a legacy framework project:
+
+```
+Read: file_path="{projectRoot}/project.json"
+```
+
+**Check these fields:**
+
+| Field | Legacy Value | Notes |
+|-------|-------------|-------|
+| `targetFramework` | `"Legacy"` | May be absent in very old projects (pre-2021), which implies Legacy |
+| `expressionLanguage` | `"VisualBasic"` (most common) or `"CSharp"` | Determines expression syntax in XAML |
+| `studioVersion` | Typically `< 23.x` | Older Studio versions |
+| `dependencies` | Classic package versions (no modern package IDs) | Very old projects (pre-2021) may have lower versions like ≤ 22.x |
+
+**If `targetFramework` is `"Windows"` or `"Portable"`**, this is a modern project — use the `uipath-rpa` skill instead.
+
+**If `targetFramework` is absent**, check the `studioVersion` and `dependencies` fields. Old projects without explicit `targetFramework` are Legacy by default.
+
+---
+
+## Step 0.3: Authentication (If Needed)
+
+Some operations (cloud-based NuGet feeds, Orchestrator assets) may require authentication:
+
+```bash
+uip login
+```
+
+This opens a browser-based login flow. Authentication is typically needed only for:
+- Projects that use private NuGet feeds requiring authentication
+- `build` commands that push packages to Orchestrator
+- Accessing Orchestrator resources (assets, queues) during `debug` execution
+
+For most local development tasks (validate, edit, find-activities), authentication is **not required**.
+
+---
+
+## Step 0.4: Package Restore
+
+After creating or modifying `project.json` dependencies, packages must be restored before `find-activities` or `type-definition` will work.
+
+**Trigger restore** by running validate on the project directory:
+
+```bash
+uip rpa-legacy validate "{projectRoot}" --output json
+```
+
+This resolves NuGet packages from configured feeds. After this completes, `find-activities` and `type-definition` will have access to the package assemblies.
+
+**If `find-activities` returns "No assemblies resolved from package dependencies"**, run validate first to trigger restore.