2.2 Configuration Management: Settings, Constants, and Assets

2.2 Configuration Management: Settings, Constants, and Assets

Core Concept: Enterprise automation solutions must strictly separate program logic from operational parameters. UiPath REFramework implements externalized configuration through Data\Config.xlsx and the InitAllSettings.xaml workflow. At runtime, these parameters are compiled into an in-memory Dictionary<string, object>, ensuring that environment endpoints, operational thresholds, and Orchestrator assets can be altered without modifying or recompiling the underlying automation package.

Hardcoded strings, static timeouts, and embedded environment URLs represent severe technical debt in enterprise RPA. If a test server changes its DNS hostname or an API gateway timeout requires extension from 30 seconds to 60 seconds, a hardcoded process requires source code modification, version bumping, peer review, and re-deployment through CI/CD pipelines. By isolating variables in Data\Config.xlsx and UiPath Orchestrator, developers ensure that processes remain fully configurable across Development, Test, UAT, and Production environments.

---

1. Anatomy of Data\Config.xlsx

The standard configuration file is stored in the project's root subdirectory under Data\Config.xlsx. It is structured into three standard worksheets, each serving a distinct operational role:

Data\Config.xlsx
├── [Worksheet] Settings   --> Business & Environment-specific parameters (URLs, file paths, switches)
├── [Worksheet] Constants  --> Core Framework mechanics & thresholds (MaxRetryNumber, timeouts, queue names)
└── [Worksheet] Assets     --> UiPath Orchestrator Assets to fetch dynamically at startup

The Settings Sheet

The Settings sheet houses environment-specific and business-level parameters. It contains three columns: Name, Value, and Description.

• Name: The unique string key used to index the configuration dictionary (e.g., "ACME_URL", "InvoiceExportDirectory", "BatchProcessingLimit").
• Value: The setting value (e.g., "https://acme-test.uipath.com", "C:\Automation\Invoices\", 50).
• Description: Human-readable documentation detailing what the parameter controls, its acceptable values, and which systems it impacts.

Typical entries on the Settings sheet include portal URLs, shared network folder paths, email notification distribution lists, and feature toggles (such as "EnableDetailedLogging" = True). The template itself ships with three rows here: OrchestratorQueueName, OrchestratorQueueFolder, and logF_BusinessProcessName.

The Constants Sheet

The Constants sheet defines how the framework itself behaves. Like Settings, it uses Name, Value, and Description columns. The values below are the ones the template ships with. Teams often add rows such as timeout values, but those are project additions, not template defaults.

The Assets Sheet

The Assets sheet links the robot to centralized, centrally managed configuration objects stored within UiPath Orchestrator. The sheet contains four columns:

• Asset: The exact asset name as registered in UiPath Orchestrator.
• Name: The local key name under which the retrieved asset value will be stored inside the Config dictionary. In standard implementations, Name is set identical to Asset.
• OrchestratorAssetFolder: The Orchestrator folder (such as "Shared", "Finance/Production", or empty for default root folder) containing the asset.
• Description: Informational context outlining the asset's purpose and security classification.

---

2. Execution Mechanics of InitAllSettings.xaml

The InitAllSettings.xaml workflow is responsible for reading Data\Config.xlsx and constructing the dictionary. The workflow follows a strict sequence of operations:

[Start InitAllSettings]
        │
        ▼
[Initialize Dictionary: Config = New Dictionary(Of String, Object)]
        │
        ▼
[For Each Sheet in {"Settings", "Constants"}]
        │
        ├─► [Read Range: Read sheet into DataTable]
        │
        └─► [For Each Row in DataTable]
                │
                ├─► [Check: Not String.IsNullOrWhiteSpace(row("Name").ToString.Trim)]
                │
                └─► [Assign: Config(row("Name").ToString.Trim) = row("Value")]
        │
        ▼
[Read Range: Read "Assets" sheet into dt_Assets]
        │
        ▼
[For Each Row in dt_Assets]
        │
        └─► [TryCatch Block]
                │
                ├─► [Get Asset Activity (using row("Asset") and folder)]
                │
                ├─► [Assign: Config(row("Name").ToString.Trim) = AssetValue]
                │
                └─► [Catch Exception: log a Warn message and continue]
        │
        ▼
[Output: out_Config returned to Main.xaml]

Step-by-Step Breakdown:

1. Dictionary Instantiation:

   out_Config = New Dictionary(Of String, Object)
   

   The dictionary is initialized with string keys and Object values, allowing it to store heterogeneous data types.

2. Parsing Local Sheets (Settings and Constants):

   • The workflow loops over an array of sheet names: {"Settings", "Constants"}.
   • The Read Range activity loads each sheet into a temporary DataTable.
   • A For Each Row activity iterates through the rows, filtering out blank lines or header comments:

     If Not String.IsNullOrWhiteSpace(row("Name").ToString.Trim) Then
         out_Config(row("Name").ToString.Trim) = row("Value")
     End If
     

3. Resolving Orchestrator Assets:

   • The workflow reads the Assets sheet into dt_Assets.
   • For each row containing a non-empty Asset name, the workflow executes the Get Asset activity.
   • If an Orchestrator folder is specified in row("OrchestratorAssetFolder"), the activity directs the query to that specific folder hierarchy.
   • The returned asset value is stored into the dictionary under row("Name").ToString.Trim.

4. Defensive Asset Exception Handling:

   • Each asset lookup sits inside a TryCatch activity.
   • If an asset cannot be found (misspelled name, wrong folder, or missing permission), the template logs a Warn message such as Loading asset ACME_URL failed: ... and moves on to the next row. It does not rethrow.
   • The key is simply never added to Config, so the problem surfaces later as a KeyNotFoundException the first time a workflow reads that key.
   • For assets the process cannot run without, add your own check (or a Rethrow in that Catch) so the job fails fast in Initialization rather than in the middle of a transaction.

---

3. Data Boxing and Type Casting in VB.NET

Because the Config dictionary is defined as Dictionary<string, object>, every value stored inside it is boxed as a System.Object. When accessing parameters in business workflows, developers must unbox or cast the object into its strongly typed representation.

' Common Unboxing and Conversion Patterns in REFramework (VB.NET)

' 1. String Extraction
Dim targetUrl As String = Config("ACME_URL").ToString

' 2. Integer Conversion (Timeouts, Counters, Port Numbers)
Dim timeoutMs As Integer = Convert.ToInt32(Config("TimeoutMedium"))
Dim maxRetries As Integer = CInt(Config("MaxRetryNumber"))

' 3. Boolean Conversion (Feature Flags, Switches)
Dim isDebugMode As Boolean = Convert.ToBoolean(Config("EnableDebugMode"))
Dim autoSendEmail As Boolean = CBool(Config("SendNotificationEmails"))

' 4. Double / Decimal Conversion (Financial thresholds, limits)
Dim approvalThreshold As Double = CDbl(Config("InvoiceThresholdAmount"))

' 5. TimeSpan Conversion
Dim delayDuration As TimeSpan = TimeSpan.FromSeconds(Convert.ToDouble(Config("DelayBetweenRequests")))

Defensive Key Access

Attempting to access a key that does not exist in the dictionary throws a System.Collections.Generic.KeyNotFoundException: The given key was not present in the dictionary.

To prevent unhandled runtime errors when reading optional settings, developers use defensive ternary checks:

' Safe Dictionary Access Pattern
Dim reportFolder As String = If(Config.ContainsKey("ReportDirectory"), 
                                Config("ReportDirectory").ToString, 
                                "C:\DefaultReports\")

---

4. Orchestrator Assets vs. Local Settings

Architecting enterprise automations requires deciding which parameters belong in Data\Config.xlsx and which belong in UiPath Orchestrator Assets:

Managing Credentials Securely

The enterprise best practice for managing login credentials in REFramework is:

1. Store the credential in UiPath Orchestrator as an Asset of type Credential.
2. In Data\Config.xlsx under the Assets or Settings sheet, store only the name of the credential asset (e.g., "ACME_Credential").
3. Inside the specific application login workflow (e.g., ACME_Login.xaml), pass Config("ACME_Credential").ToString into a Get Credential activity.
4. The Get Credential activity outputs the username as a String and the password as a System.Security.SecureString.
5. Pass the SecureString directly into modern Type Into (with SecureText enabled) or Use Application/Browser activities without ever converting it to plaintext in memory.

+-----------------------------------------------------------------------------------+
| SECURE CREDENTIAL ARCHITECTURE                                                    |
|                                                                                   |
|  [Config.xlsx]                     [UiPath Orchestrator]                          |
|  Key: "ACME_CredentialName"        Asset Name: "ACME_Credential"                  |
|  Value: "ACME_Credential"          Type: Credential (Encrypted)                   |
|           │                                  │                                    |
|           ▼                                  ▼                                    |
|  [Main.xaml / Config Dictionary]             │                                    |
|  Config("ACME_CredentialName") ──────────────┤                                    |
|                                              ▼                                    |
|                                 [Get Credential Activity]                         |
|                                 in_CredentialName = "ACME_Credential"             |
|                                              │                                    |
|                                     ┌────────┴────────┐                           |
|                                     ▼                 ▼                           |
|                              out_Username       out_Password                      |
|                              (String)           (System.Security.SecureString)    |
|                                     │                 │                           |
|                                     └────────┬────────┘                           |
|                                              ▼                                    |
|                                    [Type Into (Secure)]                           |
+-----------------------------------------------------------------------------------+

---

5. Architectural Best Practices for Configuration Management

1. Treat Config as Read-Only at Runtime: The Config dictionary should be populated strictly during Initialization. Do not write code that modifies or inserts keys into Config during Process Transaction. Mutating global configuration during transactional execution creates race conditions, impairs debugging, and violates modular workflow encapsulation.
2. Pass in_Config Strictly by Value: When invoking child workflows from Main.xaml or Process.xaml, pass the configuration object using the direction In (in_Config). Do not use InOut (io_Config) unless a workflow's explicit purpose is configuration modification.
3. Standardize Naming Conventions: Prefix asset keys logically to clarify their system affiliation and type (e.g., ACME_URL, ACME_Credential, SAP_ClientNumber, Timeout_Short).
4. Modern Folder Scoping: Always populate the OrchestratorAssetFolder column when working in modern Orchestrator folder hierarchies. This ensures the robot queries the correct tenant subfolder rather than failing on an ambiguous asset query.