.NET SDK — Client Reference: WizardClient¶

Overview¶

WizardClient generates and validates configuration wizard models and saves configuration changes. It is primarily used by AIForged Studio’s Service Configuration Wizard, where steps are dynamically generated based on the service type. You can also use it programmatically to bootstrap and configure new services.

• Generate wizard steps for an existing service in a project.
• Bootstrap a new service and receive the required wizard steps.
• Validate a single step or multiple steps.
• Save step changes and re-validate until complete.

Prerequisites¶

1. Initialize the SDK and obtain WizardClient.

   using AIForged.API;
   using System;
   using System.Collections.Generic;
   using System.Collections.ObjectModel;
   using System.Threading;
   using System.Threading.Tasks;
   
   var baseUrl = Environment.GetEnvironmentVariable("AIFORGED_BASE_URL") ?? "https://portal.aiforged.com";
   var apiKey  = Environment.GetEnvironmentVariable("AIFORGED_API_KEY")  ?? throw new Exception("AIFORGED_API_KEY not set.");
   
   var cfg = new Config { BaseUrl = baseUrl, Timeout = TimeSpan.FromMinutes(5) };
   await cfg.Init();
   cfg.HttpClient.DefaultRequestHeaders.Add("X-Api-Key", apiKey);
   
   var ctx = new Context(cfg);
   var wizard = ctx.WizardClient;
   

Methods¶

Get all wizard steps¶

Returns all wizard steps for a project and a service.

Signatures

Task<PortalResponse<ObservableCollection<Wizard>>> GetAllAsync(int? projectId, int? stpdId, bool? validate);
Task<PortalResponse<ObservableCollection<Wizard>>> GetAllAsync(int? projectId, int? stpdId, bool? validate, CancellationToken cancellationToken);

Example

var steps = (await wizard.GetAllAsync(projectId: 1001, stpdId: 2001, validate: true)).Result;
foreach (var s in steps)
{
    Console.WriteLine($"{s.Index}: {s.Name} [{s.State}] - {s.Description}");
}

Bootstrap a new service (get steps)¶

Creates the initial service definition and returns the wizard steps required to complete configuration.

Signatures

Task<PortalResponse<ObservableCollection<Wizard>>> CreateServiceAsync(int? projectId, ParameterDefViewModel stpd);
Task<PortalResponse<ObservableCollection<Wizard>>> CreateServiceAsync(int? projectId, ParameterDefViewModel stpd, CancellationToken cancellationToken);

Example

var stpd = new ParameterDefViewModel
{
    // Populate fields required for your service type
    // (e.g., Name, ServiceTypeId, Options). Provide only valid fields for your environment.
};
var steps = (await wizard.CreateServiceAsync(projectId: 1001, stpd: stpd)).Result;

Validate a single step¶

Validates a wizard step for a project.

Signatures

Task<PortalResponse<Wizard>> ValidateAsync(int? projectId, WizardValidation? type, Wizard wizard);
Task<PortalResponse<Wizard>> ValidateAsync(int? projectId, WizardValidation? type, Wizard wizard, CancellationToken cancellationToken);

Example

var step = steps[0];
// Update fields on step.STPD, step.PD, etc., as needed...

var validated = (await wizard.ValidateAsync(
    projectId: 1001,
    type: WizardValidation.Options, // e.g., Steps, Options, BeforeSave, AfterSave
    wizard: step
)).Result;

Console.WriteLine($"Step '{validated.Name}' state: {validated.State} Error: {validated.Error}");

Validate multiple steps¶

Validates multiple wizard steps in one call.

Signatures

Task<PortalResponse<ObservableCollection<Wizard>>> ValidateMultiAsync(int? projectId, List<Wizard> wizards);
Task<PortalResponse<ObservableCollection<Wizard>>> ValidateMultiAsync(int? projectId, List<Wizard> wizards, CancellationToken cancellationToken);

Example

var allValidated = (await wizard.ValidateMultiAsync(projectId: 1001, wizards: new List<Wizard>(steps))).Result;

Save a wizard step¶

Persists changes for a single wizard step.

Signatures

Task<PortalResponse<Wizard>> SaveAsync(int? projectId, Wizard wizard);
Task<PortalResponse<Wizard>> SaveAsync(int? projectId, Wizard wizard, CancellationToken cancellationToken);

Example

// Assuming 'step' has been validated successfully
var saved = (await wizard.SaveAsync(projectId: 1001, wizard: step)).Result;
Console.WriteLine($"Saved step '{saved.Name}' with state: {saved.State}");

Typical workflows¶

Create and configure a new service¶

1. Prepare an initial ParameterDefViewModel for the service.

   var stpd = new ParameterDefViewModel
   {
       // Supply fields appropriate for your service type
   };
   

2. Bootstrap the service and get steps.

   var steps = (await wizard.CreateServiceAsync(projectId: 1001, stpd: stpd)).Result;
   

3. Iterate steps in order. For each step:

   • Apply changes to the step model (for example, STPD, PD).
   • Validate the step.
   • Save the step if valid.

   foreach (var step in steps)
   {
       // Apply updates to step here...
   
       var validated = (await wizard.ValidateAsync(1001, WizardValidation.Options, step)).Result;
       if (validated.State == WizardState.Error)
       {
           Console.WriteLine($"Step {validated.Index} error: {validated.Error}");
           break;
       }
   
       var saved = (await wizard.SaveAsync(1001, validated)).Result;
       Console.WriteLine($"Saved step {saved.Index}: {saved.State}");
   }
   

4. Re-fetch steps and validate all to confirm completion.

   var finalSteps = (await wizard.GetAllAsync(1001, stpdId: saved.STPD?.Id, validate: true)).Result;
   

flowchart TD
    A["CreateServiceAsync"] --> B["Get steps"]
    B["Get steps"] --> C["Validate step"]
    C["Validate step"] --> D{"State OK?"}
    D -- "Yes" --> E["Save step"]
    D -- "No" --> F["Adjust inputs"]
    E --> G["Next step"]
    F --> C
    G --> H["GetAllAsync (validate=true)"]

Fetch and validate existing service steps¶

1. Load steps for a service.

   var steps = (await wizard.GetAllAsync(projectId: 1001, stpdId: 2001, validate: true)).Result;
   

2. Fix any step with Error or Warning state and re-validate.

   foreach (var s in steps)
   {
       if (s.State == WizardState.Error || s.State == WizardState.Warning)
       {
           // Apply corrections to s ...
           var validated = (await wizard.ValidateAsync(1001, WizardValidation.Options, s)).Result;
           var saved = (await wizard.SaveAsync(1001, validated)).Result;
       }
   }
   

flowchart LR
    A["GetAllAsync (validate=true)"] --> B{"Any errors?"}
    B -- "Yes" --> C["Update step"]
    C --> D["ValidateAsync"]
    D --> E["SaveAsync"]
    E --> A
    B -- "No" --> F["Done"]

Models¶

Wizard¶

Enums¶

Enum Table Format Correction¶

Overview¶

You are right. I deviated from our agreed enum table format. The standard we confirmed is:

• For enums, always use a 2-column table:
• Value
• Numeric Value

This page explains the slip and provides corrected tables using the exact header “Numeric Value”.

Root cause and resolution¶

• Root cause
• I applied a shortened column header (“Numeric”) in some sections instead of the exact “Numeric Value”.
• Resolution
• Adopt and enforce the precise header “Numeric Value” for all enum tables going forward.
• Retrofit recent pages, starting with the latest clients you requested.

Corrected enums — VerificationClient¶

VerificationType¶

VerificationStatus¶

DayOfWeek¶

WizardType¶

WizardState¶

WizardValidation¶

Next steps¶

1. I will keep the “Numeric Value” header consistent across all future enum tables.
2. If you want, I can retrofit any prior pages you specify to ensure every enum section uses the exact format.

Troubleshooting¶

• Step remains in Error
  • Validate the step and inspect Error and Warning fields for guidance. Some steps depend on earlier steps—verify Index order and re-validate prerequisites.
• Save appears to succeed but later validation fails
  • Re-run GetAllAsync with validate: true to compute step status after changes. Adjust inputs and re-validate.
• Creating a service returns unexpected steps
  • Confirm the fields provided in ParameterDefViewModel match the intended service type’s expectations. Validate the first step to get actionable feedback.
• Multiple steps fail concurrently
  • Use ValidateMultiAsync to assess all steps after a batch of changes, then correct the most fundamental (lowest Index) steps first.