afv-library/skills/building-omnistudio-callable-apex/examples/Test_VlocityOpenInterface2Conversion/TRANSCRIPT.md

Reasoning Transcript: VlocityOpenInterface2 → Callable Conversion (MyCustomRemoteClass)

This document records the reasoning process and skills used to convert MyCustomRemoteClass.cls (VlocityOpenInterface2) to MyCustomCallable.cls and create MyCustomCallableTest.cls.

---

Task Summary

Convert a VlocityOpenInterface2 implementation (MyCustomRemoteClass) to System.Callable, add a test class, and document reasoning and skills used.

---

Source Analysis

Original class: MyCustomRemoteClass.cls

• Implements: omnistudio.VlocityOpenInterface2
• Action: calculateTotal
• Input contract: inputMap with keys price (Decimal), quantity (Decimal)
• Output contract: outputMap.put('total', price * qty)
• Behavior: Single action; returns true on success, false for unsupported methods

---

Skills Applied

1. building-omnistudio-callable-apex (Primary)

Path: skills/building-omnistudio-callable-apex/SKILL.md
Trigger: Callable implementations, VlocityOpenInterface, migration to System.Callable

Application:

• Migration guidance (SKILL § Migration: VlocityOpenInterface to System.Callable):

  • Preserved action name: calculateTotal → action in call()
  • Pass inputMap and options as keys in args: { 'inputMap' => inputMap, 'options' => options }
  • Return response envelope instead of mutating outputMap
  • Keep call() thin; delegate to calculateTotal(inputMap, options)
  • Backward compatibility: if args lacks inputMap, treat args as inputMap

• Callable skeleton (SKILL § Phase 3 – Callable skeleton):

  • Extracted inputMap and options from args with null guards
  • switch on action with when else throwing IndustriesCallableException

• Response envelope:

  { success, data: { total }, errors }
  

• Input validation: Added toDecimal() and toInteger() type coercion (OmniScript often passes strings); return error envelope when price or quantity is null or invalid.

• Contract & Dispatch: Explicit action list; typed exception for unsupported actions.

---

2. generating-apex (Reference)

Path: ~/.claude/skills/generating-apex/SKILL.md
Trigger: Apex classes, code quality

Application:

• ApexDoc on class and key methods
• with sharing on the callable class
• Null-safe input handling; no direct casts without validation
• Naming: MyCustomCallable (callable pattern; preserves "MyCustom" from source)

---

3. running-apex-tests (Reference)

Path: ~/.claude/skills/running-apex-tests/SKILL.md
Trigger: Apex tests

Application:

• Positive: Success with inputMap/options, flat args, and string inputs (type coercion)
• Contract: Missing price, missing quantity, null args → error envelope
• Negative: Unsupported action throws IndustriesCallableException
• GIVEN/WHEN/THEN implied via clear assertions and method names

---

Design Decisions

Decision	Rationale
Preserve lowercase keys (price, quantity, total)	Original MyCustomRemoteClass used lowercase; maintains contract for existing Integration Procedures / OmniScripts
Response envelope	Aligns with Industries pattern; callers get consistent success, data, errors shape
Error envelope for validation	Return structured errors instead of throwing; callers can handle without try/catch
Exception for unsupported action	Skill pattern; IndustriesCallableException makes misuse explicit
Type coercion helpers	OmniScript/Integration Procedures often pass strings; toDecimal/toInteger allow '25.00', '4' etc.
Flat args fallback	When args lacks inputMap, treat args as inputMap for backward compatibility

---

Artifacts Produced

1. IndustriesCallableException.cls – Custom exception for unsupported actions
2. MyCustomCallable.cls – Callable implementation (converted from MyCustomRemoteClass)
3. MyCustomCallableTest.cls – Test class (7 methods)
4. TRANSCRIPT.md – This reasoning transcript

---

Contract Mapping (Before → After)

VlocityOpenInterface2	System.Callable
methodName = 'calculateTotal'	action = 'calculateTotal'
inputMap.get('price'), inputMap.get('quantity')	Same keys in args.inputMap or flat args
outputMap.put('total', ...)	return { success => true, data => { total => ... } }
return false for unsupported	throw IndustriesCallableException
options (unused in original)	Passed through for future use

---

Deployment Notes

Copy the .cls files into your Salesforce project under force-app/main/default/classes/ and add the corresponding -meta.xml files. No SOQL/DML; no special API version requirements.