In this post, we explore how to build a Custom Trace Parser directly in X++. By leveraging the standard Microsoft.Dynamics.AX.Services.Tracing.TraceParser libraries (the same ones used by the “Troubleshoot” app in the standard application), we can start, stop, and parse traces entirely via code.

The Challenge

The standard Trace Parser is a powerful GUI tool, but accessing that data programmatically is difficult. The event definitions are often internal, and mapping SQL bind variables to their statements requires complex logic.

However, the D365FO environment includes the necessary DLLs to handle this. Specifically, we can utilize:

• Microsoft.Dynamics.AX.Services.Tracing.TraceParser.dll (Referenced in ApplicationSuite)
• Microsoft.Dynamics.AX.Services.Tracing.Crimson.dll (Referenced in AppTroubleshooting)

The Solution

We can create a wrapper class that implements System.IDisposable. This allows us to use a using block to automatically start a trace and ensure it stops and cleans up the ETL file when execution finishes.

The core components of this solution are:

1. SysTraceController: To start and stop the session tracing.
2. EventTraceWatcher: To read the generated ETL file.
3. SqlFormatter: To inject bind variables back into the SQL statements for readability.

The Implementation

Below is a custom class, SysTraceParser_BET, that handles the orchestration. Note that we have to define some EventId constants manually (like 24500 for Method Enter) because the original enum is not accessible by X++.

using Microsoft.Dynamics.AX.Services.Tracing.TraceParser;
using Microsoft.Dynamics.AX.Services.Tracing.TraceParser.DataServices;
using Microsoft.Dynamics.AX.Services.Tracing.TraceParser.TraceEvents;
using Microsoft.Dynamics.AX.Services.Tracing.Crimson;
using Microsoft.Dynamics.AX.Services.Tracing.TraceParser.Presentation;
using System.Diagnostics.Eventing.Reader;

final internal class SysTraceParser_BET implements System.IDisposable
{
    // EventId values are set in enum Microsoft.Dynamics.AX.Services.Tracing.TraceParser.TraceEvents.MicrosoftDynamicsAXExecutionTracesFactory+RainierXppEventDescriptors
    // these are not accessible directly in x++, so we define them here again

    // SQL
    private const str PropertySqlStatement = 'sqlStatement';
    private const str PropertySqlBindVarValue = 'parameterValue';
    private const str PropertySqlColumnId = 'sqlColumnId';
    private const str PropertyExecutionTimeSeconds = 'executionTimeSeconds'; // New constant
    private const int AosSqlStatementExecutionLatency = 4922;
    private const int AosSqlStatementInputBind = 4923;

    // XPP
    private const str PropertyMethodName = 'methodName';
    private const int XppMethodEnter = 24500;
    private const int XppMethodExit = 24501;    

    private static TraceParserOrchestrator traceParserOrchestrator = new TraceParserOrchestrator();

    private str traceName;
    private SysTraceParserTable_BET traceParserTable;
    private boolean persistLog;

    private int traceId;
    private boolean imported;
    private boolean isRunning;
    private Filename etlFileName;
    private BindVariables BindParameters = new BindVariables();
    private Map sqlStatements = new Map(Types::Integer, Types::String);
    private Map sqlStatementsWithValues = new Map(Types::Integer, Types::String);

    private int stackDepth = 0;
    
    private SysTraceParserCallTreeNode_BET rootNode, currentNode;

    private void init()
    {
        rootNode = new SysTraceParserCallTreeNode_BET(SysTraceParserCallTreeNodeType_BET::Xpp);
        rootNode.IsRootNode = true;

        currentNode = rootNode;
    }

    internal void startTrace(boolean _persistLog = false)
    {
        System.Exception exception;
        try
        {
            if (_persistLog && !traceParserTable)
            {
                traceParserTable = SysTraceParserTable_BET::create(traceName, SysTraceMarkerType_BEC::ThreadId, guid2Str(getCurrentThreadActivityId()));
            }

            SysTraceParserTable_BET::start(traceParserTable);            

            TraceParserOrchestrator::StartTraceOptimized(traceName);
            isRunning = true;            
        }
        catch(exception)
        {
            error(exception.get_Message());
        }

        if (isRunning)
        {
            this.awaitTraceParser();
        }
    }

    internal void stopTrace()
    {
        if (!isRunning)
        {
            return;
        }

        this.awaitTraceParser();

        System.Exception exception;
        try
        {
            TraceParserOrchestrator::StopTrace(traceName);
            isRunning = false;
        }
        catch(exception)
        {
            error(exception.get_Message());
        }

        if (!isRunning)
        {
            etlFileName = traceParserOrchestrator.GetEtlFilePath(traceName);

            SysTraceParserTable_BET::stop(traceParserTable, etlFileName);
        }
    }

    private void parseEtlRow(System.Object _sender, EventArrivedEventArgs _e)
    {
        var factory = AxTraceEventFactory::GetFactory(_e.Header.ProviderId);
        if (factory == null)
        {
            return;
        }

        if(!AxTraceEventFactory::IsDynamicsProvider(_e.Header.ProviderId))
        {
            return;
        }
        
        AxTraceEvent traceEvent = factory.Create(_e); 
        
        if (traceParserTable && traceParserTable.MarkerType == SysTraceMarkerType_BEC::ThreadId)
        {
            if (guid2Str(traceEvent.ActivityId) != traceParserTable.MarkerName)
            {
                return;
            }
        }
        // if user selected, traceEvent.SessionName contains user guid
        // also check if is batch or user?
        // if (...)
        else if (traceEvent.ActivityId != getCurrentThreadActivityId())
        {
            return;
        }        

        var bindValues = BindParameters.Values;

        Microsoft.Dynamics.AX.Services.Tracing.Crimson.EventHeader header = _e.Header;
        int64 currentTicks = header.TimeStamp; 

        switch (traceEvent.EventId)
        {
            case XppMethodEnter:
                str method = 'Unknown';
                if (_e.Properties.ContainsKey(PropertyMethodName))
                {
                    method = _e.Properties.Get_Item(PropertyMethodName).ToString();
                }

                SysTraceParserCallTreeNode_BET xppNode = new SysTraceParserCallTreeNode_BET(SysTraceParserCallTreeNodeType_BET::Xpp, currentNode);
                xppNode.StartTicks = currentTicks;
                xppNode.ExecutionLog = method;
                xppNode.StackDepth = stackDepth;

                currentNode.addChild(xppNode);

                currentNode = xppNode;
                
                stackDepth++;
                break;

            case XppMethodExit:
                if (currentNode != null && currentNode != rootNode)
                {
                    currentNode.DurationMs = (currentTicks - currentNode.StartTicks) / 10000;

                    currentNode = currentNode.Parent;

                    stackDepth--;
                    if (stackDepth < 0)
                    {
                        stackDepth = 0;
                    }
                }
                break;

            case AosSqlStatementExecutionLatency:
                if (_e.Properties.ContainsKey(PropertySqlStatement))
                {
                    str sqlStatement = _e.Properties.Get_Item(PropertySqlStatement);
                    str sqlStatementWithValues = SqlFormatter::BindParameters(sqlStatement, bindValues.Values);
                    sqlStatements.add(sqlStatements.elements(), sqlStatement);
                    sqlStatementsWithValues.add(sqlStatementsWithValues.elements(), sqlStatementWithValues);

                    real sqlDurationMs = 0;
                    if (_e.Properties.ContainsKey(PropertyExecutionTimeSeconds))
                    {
                        sqlDurationMs = any2Real(_e.Properties.Get_Item(PropertyExecutionTimeSeconds)) / 1000;
                    }

                    SysTraceParserCallTreeNode_BET sqlNode = new SysTraceParserCallTreeNode_BET(SysTraceParserCallTreeNodeType_BET::Sql, currentNode);
                    sqlNode.StartTicks = currentTicks;
                    sqlNode.ExecutionLog = sqlStatementWithValues;
                    sqlNode.DurationMs = sqlDurationMs;
                    sqlNode.StackDepth = stackDepth;
                    
                    currentNode.addChild(sqlNode);
                }
                bindValues.Clear();
                break;

            case AosSqlStatementInputBind:
                if (_e.Properties.ContainsKey(PropertySqlColumnId) &&
                    _e.Properties.ContainsKey(PropertySqlBindVarValue))
                {
                    int columnId = any2Int(_e.Properties.Get_Item(PropertySqlColumnId).ToString())-1;
                    str parameterValue = _e.Properties.Get_Item(PropertySqlBindVarValue);
                    if (bindValues.ContainsKey(columnId))
                    {
                        bindValues.Clear();
                    }
                    bindValues.Add(columnId, parameterValue);
                }
                break;
        }
    }

    internal void import()
    {
        if (isRunning)
        {
            this.stopTrace();
        }

        if (etlFileName)
        {            
            AxTraceEventFactory::PrepareProivdersMap();

            using (var watcher = new EventTraceWatcher())
            {
                watcher.EventArrived += eventhandler(this.parseEtlRow);
                try
                {
                    watcher.ProcessTrace(etlFileName);
                    imported = true;
                }
                finally
                {
                    watcher.EventArrived -= eventhandler(this.parseEtlRow);
                }
            }            
        }
    }

    private void awaitTraceParser()
    {
        infolog.yield();
        sleep(5000);
        infolog.yield();
    }

    internal Map sqlStatementsWithParameterValues()
    {
        return sqlStatementsWithValues;
    }

    internal Map sqlStatements()
    {
        if (!imported)
        {
            this.import();
        }
        
        return sqlStatements;
    }

    internal SysTraceParserCallTreeNode_BET getCallTreeRootNode()
    {
        if (!imported)
        {
            this.import();
        }
        return rootNode;
    }

    public void Dispose()
    {
        if (isRunning)
        {
            TraceParserOrchestrator::StopTrace(traceName);

            traceParserOrchestrator.Cleanup(traceName);
        }

        if (etlFileName && System.IO.File::Exists(etlFileName))
        {
            traceParserOrchestrator.Cleanup(traceName);
        }
    }

    public void persistTraceParserTable()
    {
        if (!traceParserTable)
        {
            return;
        }

        SysTraceParserCallTreeNode_BET rootNodeLoc = this.getCallTreeRootNode();
        RecordInsertList rilLog = new RecordInsertList(tableNum(SysTraceParserLog_BET), true, true, true, true, true);

        this.persistNode(rootNodeLoc, rilLog);
        
        rilLog.insertDatabase();

    }

    private void persistNode(SysTraceParserCallTreeNode_BET _node, RecordInsertList _ril)
    {
        if (!_node.IsRootNode)
        {
            SysTraceParserLog_BET log;

            log.SysTraceParserTableRefRecId = traceParserTable.RecId;
            log.CallTreeNodeType = _node.NodeType;
            log.SysTraceTextDetails = _node.ExecutionLog;
            log.DurationMs = _node.DurationMs;

            _ril.add(log);
        }

        ListEnumerator it = _node.Children.getEnumerator();
        while (it.moveNext())
        {
            this.persistNode(it.current(), _ril);
        }
    }

    static internal SysTraceParser_BET newFromTraceName(str _traceName)
    {
        Debug::assert(_traceName != '');

        SysTraceParser_BET traceParser = new SysTraceParser_BET();
        traceParser.traceName = _traceName;

        traceParser.init();

        return traceParser;
    }

    static internal SysTraceParser_BET newFromTraceTable(SysTraceParserTable_BET _traceParserTable)
    {
        Debug::assert(_traceParserTable.TraceName != '');

        SysTraceParser_BET traceParser = new SysTraceParser_BET();

        if (_traceParserTable.EtlFileName)
        {
            traceParser.etlFileName = _traceParserTable.EtlFileName;
        }
        else
        {
            traceParser.traceName = _traceParserTable.TraceName;
            traceParser.traceParserTable = _traceParserTable;
        }

        traceParser.init();

        return traceParser;
    }

}

internal final class SysTraceParserCallTreeNode_BET
{
    public SysTraceParserCallTreeNodeType_BET NodeType;

    public str ExecutionLog;
    public int64 StartTicks;
    public real DurationMs;
    public int StackDepth;
    public List Children;
    public SysTraceParserCallTreeNode_BET Parent;

    public boolean IsRootNode;

    public void new(SysTraceParserCallTreeNodeType_BET _nodeType, SysTraceParserCallTreeNode_BET _parent = null)
    {
        NodeType = _nodeType;
        Parent = _parent;
        Children = new List(Types::Class);
    }

    public void addChild(SysTraceParserCallTreeNode_BET _child)
    {
        Children.addEnd(_child);
    }

}

How to use it

Using the class is straightforward. You wrap the code you want to analyze in a using block. Once the block exits, the trace stops, the parser runs, and you can inspect the xppExecutionLog list.

Here is a test runnable class - note that everything is printed to infolog, which might not be really useful. This is only for demonstration purposes:

internal final class SysTraceParserTest_BET
{
    public static void main(Args _args)
    {
        str traceName = 'TestTrace_' + guid2Str(newGuid());
        
        using (SysTraceParser_BET traceParser = SysTraceParser_BET::newFromTraceName(traceName))
        {
            try
            {
                traceParser.startTrace(true);
                
                SysTraceParserTest_BET::performDatabaseOperations();

                traceParser.stopTrace();
                
                SysTraceParserTest_BET::printNodeRecursive(traceParser.getCallTreeRootNode());
            }
            catch (Exception::Error)
            {
                error('An error occurred during tracing.');
                traceParser.Dispose();
            }
        }
    }

    private static void performDatabaseOperations()
    {
        FeatureTable_BET featureTable;
        
        select firstonly featureTable;
        
        info(featureTable.feature().getDescription());
    }

    private static void printNodeRecursive(SysTraceParserCallTreeNode_BET _node)
    {
        if (!_node.IsRootNode)
        {            
            if (_node.NodeType == SysTraceParserCallTreeNodeType_BET::Xpp)
            {
                info(strFmt("%1[XPP] %2 : %3 ms", strRep('.', _node.StackDepth), _node.ExecutionLog, num2Str(_node.DurationMs, 0, 2, 1, 0)));
            }
            else
            {
                info(strFmt("%1[SQL] %2 : %3 ms", strRep('.', _node.StackDepth), _node.ExecutionLog, num2Str(_node.DurationMs, 0, 2, 1, 0)));
            }
        }

        ListEnumerator it = _node.Children.getEnumerator();
        while (it.moveNext())
        {
            SysTraceParserTest_BET::printNodeRecursive(it.current());
        }
    }

}

This is the output. As you can see, we get the full X++ call stack, including the SQL traces between the method calls. As noted previously, in this form (info messages) it’s not really useful.

..[XPP] Dynamics.AX.Application.xInfo::yield : 0.02 ms
.[XPP] Dynamics.AX.Application.SysTraceParser_BET::awaitTraceParser : 0.00 ms
[XPP] Dynamics.AX.Application.SysTraceParser_BET::stopTrace : 0.00 ms
....[XPP] Dynamics.AX.Application.xInfo::add : 0.21 ms
.......[XPP] Dynamics.AX.Application.xInfo::line : 0.02 ms
......[XPP] Dynamics.AX.Application.Info::line : 0.02 ms
.....[XPP] Dynamics.AX.Application.xGlobal::infologLine : 0.06 ms
....[XPP] Dynamics.AX.Application.Global::infologLine : 0.06 ms
---<REDACTED>---
...[XPP] Dynamics.AX.Application.FeatureFactoryAttribute_BET::new : 0.00 ms
..[XPP] Dynamics.AX.Application.FeatureStateProvider_BET::createFeatureInstance : 22.67 ms
.[XPP] Dynamics.AX.Application.FeatureTable_BET::feature : 22.69 ms
.[SQL] SELECT TOP 1 T1.FEATURECLASS,T1.ACTIVE,T1.MODIFIEDDATETIME,T1.MODIFIEDBY,T1.CREATEDDATETIME,T1.CREATEDBY,T1.RECVERSION,T1.PARTITION,T1.RECID FROM FEATURETABLE_BET T1 WHERE ((PARTITION=5637144576) AND (DATAAREAID=N'rcho')) : 0.00 ms
.[SQL] {call SysSetConnectionContextInfo ('raphael.bucher',25619,'CLIENT - read-only',0)} : 0.00 ms
[XPP] Dynamics.AX.Application.SysTraceParserTest_BET::performDatabaseOperations : 33.27 ms
[XPP] Dynamics.AX.Application.xInfo::yield : 0.14 ms

Summary

This approach allows for highly specific, code-driven performance analysis. You could extend this to:

• Assert that a specific method only calls SQL once.
• Log the actual SQL queries generated by complex queries.
• Automate performance regression testing in your build pipeline using unit tests.

By wrapping the complexity of EventTraceWatcher and TraceParserOrchestrator, we unlock the ability to treat execution traces as just another data source in X++.

To streamline this, I created a utility class SysTemporaryAdminRevoke_BET. This tool allows you to temporarily revoke your own Admin rights or, optionally, impersonate the security context of another specific user without switching accounts.

How it works

The logic relies on temporarily modifying the SecurityUserRole table within a running session. Here is the flow:

1. Launch: You run the class. (append to URL: mi=SysClassRunner&cls=SysTemporaryAdminRevoke_BET)
2. Configuration: A dialog asks if you want to mimic a specific user (optional).
3. Revocation:
   • If a user ID is provided, your current roles are swapped with that user’s roles.
   • The System Administrator role is removed from your user.
4. Pause: A dialog box (SysBoxForm) appears. As long as this box is open, your admin rights are suspended.
5. Testing: While the box is open, you can spawn new sessions (browser tabs) to test the application with the restricted rights.
6. Restoration: Closing the dialog box automatically restores your System Administrator role and reverts any role swaps.

The Code

Below is the X++ code for the class. It uses unchecked(Uncheck::TableSecurityPermission) to allow the modification of system security tables even while the rights are being adjusted.

internal final class SysTemporaryAdminRevoke_BET
{
    private static const str SystemAdministrator = 'System Administrator';
    private static const str SystemUser = 'System user';

    Set revokedUserRoles = new Set(Types::String);
    Set grantedUserRoles = new Set(Types::String);

    boolean adminRevoked;
    boolean adminGranted;

    public static void main(Args _args)
    {
        Dialog dlg = new Dialog('Temporary Admin revoke tool');
        DialogField dfSysUser = dlg.addField(extendedTypeStr(SysUserId), 'Act with user rights (optional)');

        if (!dlg.run())
        {
            return;
        }

        SysTemporaryAdminRevoke_BET adminRevoke = SysTemporaryAdminRevoke_BET::construct();
        adminRevoke.actWithUserRights(dfSysUser.value());
        adminRevoke.revokeSecurityRightsPrompt();
    }

    public static SysTemporaryAdminRevoke_BET construct()
    {
        return new SysTemporaryAdminRevoke_BET();
    }

    public void actWithUserRights(str _userId)
    {
        if (!_userId)
        {
            return;
        }

        ttsbegin;
        SecurityRole        securityRole;
        SecurityUserRole    securityUserRole;
        // Revoke current user's roles (except System User and Admin)
        while select securityUserRole
            where   securityUserRole.User == curUserId()
        join securityRole
            where   securityRole.RecId == securityUserRole.SecurityRole &&
                    securityRole.Name != SystemUser &&
                    securityRole.Name != SystemAdministrator
        {
            revokedUserRoles.add(securityRole.Name);

            this.revokeSecurityRole(securityRole.Name, securityUserRole.User);
        }

        // Grant the target user's roles to the current user
        while select securityUserRole
            where   securityUserRole.User == _userId
        join securityRole
            where   securityRole.RecId == securityUserRole.SecurityRole &&
                    securityRole.Name != SystemUser &&
                    securityRole.Name != SystemAdministrator
        {
            grantedUserRoles.add(securityRole.Name);

            this.grantSecurityRole(securityRole.Name, curUserId());
        }
        ttscommit;
    }

    public void revokeSecurityRightsPrompt()
    {
        if (!hasGUI())
        {
            throw error("@ApplicationPlatform:FormOpenNonGUISession");
        }

        // Revoke Admin
        this.revokeSecurityRole(SystemAdministrator);

        // Wait for user to finish testing
        this.waitForUser();

        // Restore Admin
        this.grantSecurityRole(SystemAdministrator);

        // Restore original roles
        if (revokedUserRoles.elements())
        {
            SetEnumerator revokedUserRolesEnum = revokedUserRoles.getEnumerator();
            while (revokedUserRolesEnum.moveNext())
            {
                this.grantSecurityRole(revokedUserRolesEnum.current());
            }
        }

        // Remove temporarily granted roles
        if (grantedUserRoles.elements())
        {
            SetEnumerator grantedUserRolesEnum = grantedUserRoles.getEnumerator();
            while (grantedUserRolesEnum.moveNext())
            {
                this.revokeSecurityRole(grantedUserRolesEnum.current());
            }
        }
    }

    private void waitForUser()
    {
        Args args = new Args();
        args.name(formstr(SysBoxForm));

        FormRun formRun = classfactory.formRunClass(args);
        formRun.init();

        SysDictClass sysBoxFormDictClass = new SysDictClass(classNum(FormRun));
        sysBoxFormDictClass.callObject(formMethodStr(SysBoxForm, setText), formRun, 'You can now spawn new sessions that will have admin rights revoked to test. Close this box to regain admin access.');
        sysBoxFormDictClass.callObject(formMethodStr(SysBoxForm, setType), formRun, DialogBoxType::InfoBox);

        formRun.run();
        formRun.wait();
    }

    public void grantSecurityRole(str _roleName, UserId _userId = curUserId())
    {
        unchecked(Uncheck::TableSecurityPermission)
        {
            SecurityRole        securityRole;
            SecurityUserRole    securityUserRole;
       
            select firstOnly securityRole
                where securityRole.Name == _roleName
            outer join securityUserRole
                where   securityUserRole.SecurityRole   == securityRole.RecId &&
                        securityUserRole.User           == _userId;

            if (!securityUserRole || (securityUserRole.AssignmentStatus != RoleAssignmentStatus::Enabled))
            {
                securityUserRole.User = _userId;
                securityUserRole.SecurityRole = securityRole.RecId;
                securityUserRole.AssignmentMode = RoleAssignmentMode::Manual;
                securityUserRole.AssignmentStatus = RoleAssignmentStatus::Enabled;

                SecuritySegregationOfDuties::assignUserToRole(securityUserRole, null);

                if (_roleName == SystemAdministrator)
                {
                    adminGranted = true;
                }
            }
        }
    }

    public void revokeSecurityRole(str _roleName, UserId _userId = curUserId())
    {
        unchecked(Uncheck::TableSecurityPermission)
        {
            if (_roleName == SystemAdministrator && adminRevoked)
            {
                return;
            }

            SecurityRole                        securityRole;
            SecurityUserRole                    securityUserRole;
            SecurityUserRoleCondition           securityUserRoleCondition;

            ttsbegin;

            select firstOnly securityRole
                where securityRole.Name == _roleName;

            delete_from securityUserRoleCondition
            exists join securityUserRole
                where   securityUserRole.RecId          == securityUserRoleCondition.SecurityUserRole &&
                        securityUserRole.User           == _userId &&
                        securityUserRole.SecurityRole   == securityRole.RecId;

            OMUserRoleOrganization userRoleOrganization;
            select firstOnly OMInternalOrganization, SecurityRole from userRoleOrganization
                where   userRoleOrganization.User           == _userId &&
                        userRoleOrganization.SecurityRole   == securityRole.RecId;

            if (userRoleOrganization.SecurityRole)
            {
                EePersonalDataAccessLogging::logUserRoleChange(userRoleOrganization.SecurityRole, userRoleOrganization.omInternalOrganization, _userId, AddRemove::Remove);

                delete_from userRoleOrganization
                    where   userRoleOrganization.User           == _userId &&
                            userRoleOrganization.SecurityRole   == securityRole.RecId;
            }

            SecuritySegregationOfDutiesConflict securitySegregationOfDutiesConflict;
            delete_from securitySegregationOfDutiesConflict
                where   securitySegregationOfDutiesConflict.User            == _userId &&
                        ((securitySegregationOfDutiesConflict.ExistingRole  == securityRole.RecId) ||
                        (securitySegregationOfDutiesConflict.NewRole        == securityRole.RecId));

            EePersonalDataAccessLogging::logUserRoleChange(securityRole.RecId, 0, _userId, AddRemove::Remove);

            delete_from securityUserRole
                where   securityUserRole.User           == _userId &&
                        securityUserRole.SecurityRole   == securityRole.RecId;

            ttscommit;

            if (_roleName == SystemAdministrator)
            {
                adminRevoked = true;
            }
        }
    }
}

Warnings and Considerations

• Non-Production Use Only: While this code is robust, manipulating security roles at runtime involves direct table writes. This should be used strictly in Dev/Test environments.
• Session State: When the waitForUser() dialog is open, your current session loses Admin rights immediately and as long as the Box dialog is not closed.
• Crash Recovery: If the client crashes or runs into a time out while the dialog is open, you might be left without Admin rights. In a Tier 1 (Dev) environment, you can restore this via SQL or by using the Admin Provisioning Tool.

[ExtensionOf(classstr(SysTableLookup))]
final class SysTableLookupClass_BEC_Extension
{
    private SysTableLookupHandler_BEC sysTableLookupHandler_BEC;

    public SysTableLookupHandler_BEC parmSysTableLookupHandler_BEC(SysTableLookupHandler_BEC _sysTableLookupHandler_BEC = sysTableLookupHandler_BEC)
    {
        sysTableLookupHandler_BEC = _sysTableLookupHandler_BEC;
        return sysTableLookupHandler_BEC;
    }

    protected FormRun formRun()
    {
        FormRun formRun_BEC = next formRun();

        if (sysTableLookupHandler_BEC)
        {
            formRun_BEC.OnClosing += eventhandler(this.onClosing_BEC);
        }

        return formRun_BEC;
    }

    private void onClosing_BEC(xFormRun _sender, FormEventArgs _eventArgs)
    {
        if (_sender.closedOk() && sysTableLookupHandler_BEC)
        {
            sysTableLookupHandler_BEC.invokeOnLookupRecordSelected_BEC(
                _sender.dataSource(1).cursor()
            );
        }
    }

}

The handler will be instantiated in your form or form extension and will be passed on the SysTableLookup class. This will act as a bridge between your form or form extension, and the SysTableLookup class.

public class SysTableLookupHandler_BEC
{
    FormRun formRun;
    MethodName formMethod;

    delegate void onLookupRecordSelected_BEC(Common _common) { }

    protected void new() { }

    public static SysTableLookupHandler_BEC construct()
    {
        return new SysTableLookupHandler_BEC();
    }

    public void invokeOnLookupRecordSelected_BEC(Common _common)
    {
        if (formRun && formMethod)
        {
            new DictClass(classIdGet(formRun))
                .callObject(formMethod, formRun, _common);
         
            return;
        }

        this.onLookupRecordSelected_BEC(_common);
    }

    public void setObjectMethodToInvoke(FormRun _formRun, MethodName _formMethod)
    {
        formRun = _formRun;
        formMethod = _formMethod;
    }

}

Inside the lookup method of your control, you use the SysTableLookup class as you normally would, but now you may set the SysTableLookupHandler to be able to get notified of what record the user selected:

SysTableLookup sysTableLookup_BEC = SysTableLookup::newParameters(tableNum(Table), _formStringControl);

Query query_BEC = new Query();
QueryBuildDataSource tableQBDS = query_BEC.addDataSource(tableNum(Table));

tableQBDS
    .addRange(fieldNum(Table, Field))
    .value(queryValue('value'));

SysTableLookupHandler_BEC tableLookupHandler_BEC = SysTableLookupHandler_BEC::construct();
sysTableLookup_BEC.parmSysTableLookupHandler_BEC(tableLookupHandler_BEC);

// either for form extensions:
sysTableLookup_BEC.setObjectMethodToInvoke(this, methodStr(Form_BEC_Extension, sysTableLookupHandler_onLookupRecordSelected_BEC));

// or for your own forms, if you want to use eventhandlers:
tableLookupHandler_BEC.onLookupRecordSelected += eventHandler(this.sysTableLookupHandler_onLookupRecordSelected_BEC);

sysTableLookup_BEC.parmQuery(query_BEC);
sysTableLookup_BEC.addLookupfield(fieldNum(Table, Field1), true);
sysTableLookup_BEC.addLookupfield(fieldNum(Table, Field2));
sysTableLookup_BEC.performFormLookup();

In your form extension class

public void sysTableLookupHandler_onLookupRecordSelected_BEC(Common _common)
{
    if (_common.TableId != tableNum(Table))
    {
        return;
    }

    // do what ever
}  

What is DebuggerDisplayAttribute?

DebuggerDisplayAttribute is a .NET attribute that allows developers to define a more meaningful string representation for objects when viewed in a debugger. While it’s commonly used in C#, it can also be leveraged in X++ classes that extend .NET objects.

Example in X++

Consider the following example of a class implementing the DebuggerDisplayAttribute:

[System.Diagnostics.DebuggerDisplayAttribute("{toString()}")]
public final class DebuggerDisplayTest_BEC
{
    public str toString()
    {
        return 'Hello World!';
    }
}

How It Works

1. The [System.Diagnostics.DebuggerDisplayAttribute("{toString()}")] line instructs the debugger to display the result of toString() when an instance of DebuggerDisplayTest_BEC is inspected.
2. The toString() method provides a human-readable string representation of the expression, making debugging much more intuitive.
3. When debugging, instead of seeing just the class name, you’ll see an output like Hello World! in this example, making it clear what the object represents.

Why Use DebuggerDisplayAttribute?

• Improved Readability: Helps in quickly identifying objects and their state.
• Faster Debugging: Reduces the need to expand object properties to understand their values.
• Better Maintenance: Makes debugging more efficient for teams working with complex object hierarchies.

Final Thoughts

The DebuggerDisplayAttribute is a small but powerful feature that can greatly enhance your debugging experience in X++. If you work with complex object structures, this attribute allows you to see meaningful information at a glance, making troubleshooting and development smoother.

Have you used DebuggerDisplayAttribute in your X++ development? Let us know in the comments!

Why Overwrite System Fields?

When importing historical data from legacy systems, it’s often important to preserve:

• Original creation timestamps (CreatedDateTime)
• Modified timestamps (ModifiedDateTime)
• User IDs who created or modified records

Without this ability, newly inserted records will have system-generated values, which could lead to inconsistencies in reporting or auditing.

How to Overwrite System Fields in X++

The following X++ example demonstrates how to override system fields when inserting data into the HcmWorkerActionCommentHistoryEntity entity:

public class HcmWorkerActionCommentHistoryEntity extends common
{
    public boolean insertEntityDataSource(DataEntityRuntimeContext _entityCtx, DataEntityDataSourceRuntimeContext _dataSourceCtx)
    {
        boolean ret = true;

        if (_dataSourceCtx.name() == dataentitydatasourcestr(HcmWorkerActionCommentHistoryEntity, HcmWorkerActionComment))
        {
            HcmWorkerActionComment workerActionComment;

            workerActionComment = _dataSourceCtx.getBuffer();

            // Enable overwriting system fields
            workerActionComment.overwriteSystemfields(true);
            
            // Preserve original CreatedDateTime
            workerActionComment.(fieldNum(HcmWorkerActionComment, CreatedDateTime)) = this.CommentCreationTime;

            workerActionComment.doInsert();
            _dataSourceCtx.setDataSaved(true);

            this.mapDataSourceToEntity(_entityCtx, _dataSourceCtx);
        }
        else
        {
            ret = super(_entityCtx, _dataSourceCtx);
        }

        return ret;
    }
}

Explanation

1. Check the correct data source: The method verifies whether the current data source is HcmWorkerActionComment before proceeding.
2. Enable system field overwriting: overwriteSystemfields(true); allows system fields to be manually set.
3. Assign the original timestamp: The CreatedDateTime field is explicitly set to this.CommentCreationTime.
4. Insert the record manually: Using doInsert(); ensures that the record is committed with the specified values.

Considerations

• Overwriting system fields should be strictly controlled and used only in migration or special scenarios.
• Ensure that the assigned values are valid and align with business rules.
• This approach bypasses system defaults, so be mindful of compliance and audit requirements.

Conclusion

By leveraging the overwriteSystemfields(true) method, you can maintain historical data integrity during migrations. This technique ensures that original timestamps and metadata remain intact, improving data accuracy and compliance in Dynamics 365 Finance & Operations.

Have you used this approach in your projects? Let me know in the comments!

Understanding System Entity Navigation

System Entity Navigation allows developers to construct URLs that navigate directly to specific records within D365 F&O. This is accomplished by specifying parameters such as the entity name and a unique identifier (GUID) for the record. When the URL is accessed, the system directs the user to the appropriate form displaying the targeted record.

For detailed information, refer to Microsoft’s documentation on System Entity Navigation.

The Role of GUIDs in System Entity Navigation

A critical component of System Entity Navigation is the GUID, which uniquely identifies a record. In D365 F&O, this GUID is derived from the combination of the TableId and RecId of the record. The process involves bitwise operations to merge these identifiers into a single GUID.

The following X++ methods illustrate how to generate and interpret these GUIDs:

// Generate a GUID from TableId and RecId
System.Guid getGuidFromTableIdRecId(TableId _tableId, RecId _recId)
{
    System.Byte[] recidBytes = System.BitConverter::GetBytes(_recId);
    System.Byte[] tableIdBytes = System.BitConverter::GetBytes(_tableId);
    int padValue = 0;
    System.Byte[] padBytes = System.BitConverter::GetBytes(padValue);
    System.Byte[] guidBytes = new System.Byte[16]();
    System.Buffer::BlockCopy(tableIdBytes, 0, guidBytes, 0, 4);
    System.Buffer::BlockCopy(padBytes, 0, guidBytes, 4, 4);
    System.Buffer::BlockCopy(recidBytes, 0, guidBytes, 8, 8);
    System.Guid recIdGuid = new System.Guid(guidBytes);

    return recIdGuid;
}

// Extract TableId and RecId from a GUID
container getTableIdRecIdFromGuid(System.Guid _recIdGuid)
{
    TableId tableId;
    RecId recId;
    System.Byte[] guidBytes = _recIdGuid.ToByteArray();
    tableId = System.BitConverter::ToInt32(guidBytes, 0);
    recId = System.BitConverter::ToInt64(guidBytes, 8);

    return [tableId, recId];
}

These methods are part of the CDSVirtualEntityConverter class and demonstrate how to encode and decode the GUIDs used in System Entity Navigation.

Integrating System Entity Navigation with Custom Link Handlers

In a previous post, we explored replacing deep links with a LinkHandler class, which processes URL parameters to locate and redirect to specific records. You can read more about this approach here.

With the understanding of how GUIDs are constructed, it’s possible to enhance the LinkHandler logic by utilizing the GUID directly. Instead of relying on parameters like tableName and searchKey, the LinkHandler can be modified to accept a GUID, from which it can derive the TableId and RecId. This streamlines the process and reduces the dependency on multiple parameters.

Conclusion

System Entity Navigation provides a robust and efficient way to create deep links within D365 F&O. By leveraging the GUIDs that encapsulate TableId and RecId, developers can simplify navigation and improve the maintainability of their code. Integrating this approach with custom link handlers offers a seamless method to direct users to specific records, enhancing the overall user experience.

Key Changes in SharePoint Authentication

Decompilation of Microsoft.Dynamics.Platform.Integration.SharePoint.dll / SharePointHelper

1. Deprecation of Existing SharePoint Authentication
   The authentication mechanism previously used for integrating with SharePoint is being removed. As of version 10.0.40, the new SharePoint user authentication feature is available but optional. However, it will become mandatory starting with version 10.0.42.

2. Migration Deadline
   By February 28, 2025, you must migrate to the new SharePoint authentication model. After this date, the current SharePoint connection method will stop working entirely.

3. Impact on Token Generation via SharePoint Proxy
   The SharePointHelper::createProxy method, which was previously used to obtain a SharePoint proxy with an access token, is now deprecated and marked for removal by version 10.0.42. Calling this method:

   SharePointHelper::createProxy(
       docuParameters.DefaultSharePointServer,
       '/',
       xUserInfo::getCurrentUserExternalId()
   );
   

   will no longer return a proxy with an access token. Although the access token might still appear when debugging (via the LegacyTokenAuthenticator), this class is now internal, making it inaccessible for external use.

One Time registration process

According to Microsoft, you should execute this script to allow application access to SharePoint after 10.0.40 for non interactive sessions. Microsoft Learn: Configure document management | One-time registration process

Import-Module Microsoft.Graph
   
# The parameter for TenantId needs to be changed
Connect-MgGraph -TenantId microsoft.onmicrosoft.com -Scopes 'Application.ReadWrite.All'
    
# These AppIds do not change as they are the first party application IDs
$erpServicePrincipal = Get-MgServicePrincipal -Filter "AppId eq '00000015-0000-0000-c000-000000000000'"
$sharePointServicePrincipal = Get-MgServicePrincipal -Filter "AppId eq '00000003-0000-0ff1-ce00-000000000000'"
$spAppRole = $sharePointServicePrincipal.AppRoles | where {$_.Value -eq 'Sites.ReadWrite.All'}
    
# Assign the SharePoint 'Sites.ReadWrite.All' permission to the Microsoft Dynamics 365 finance and operations application
New-MgServicePrincipalAppRoleAssignedTo -ServicePrincipalId $erpServicePrincipal.Id -PrincipalId $erpServicePrincipal.Id -ResourceId $sharePointServicePrincipal.Id -AppRoleId $spAppRole.Id

What Can Be Used Instead?

Temporary Solution: SharePointTokenFactory

For those encountering 401 Unauthorized errors in SharePoint API calls, the following method can be used to obtain an access token:

   using Microsoft.Dynamics.Platform.Integration.SharePoint;

   SharePointTokenFactory::GetToken(userId, domain);

This approach provides a bearer token that can authenticate SharePoint API requests. However, be cautious: while this method is currently not marked as deprecated, there’s no guarantee it will remain available in future updates. It is strongly recommended to monitor updates from Microsoft for any changes.

Long-Term Solution: Entra ID App Registration

To future-proof your integration, consider creating an app registration in Microsoft Entra ID (formerly Azure Active Directory). Using this approach, you can generate your own access tokens with either:

• Client and secret authentication, or
• Certificate-based authentication.

This ensures compliance with Microsoft’s recommended practices and prepares your system for any further changes in authentication models.

Next Steps

• Audit Your Current Integrations: Check where SharePointHelper::createProxy or similar methods are being used and plan for their removal.
• Implement Token Generation: Use SharePointTokenFactory::GetToken as a short-term workaround while transitioning to app registration.
• Prepare for Mandatory Updates: Begin configuring app registrations in Entra ID to handle token-based authentication.

The upcoming updates underscore the importance of aligning with Microsoft’s evolving security protocols. By taking proactive steps now, you can ensure uninterrupted integration with SharePoint and avoid disruptions when the current authentication model is retired.

Useful Resources

• Microsoft Documentation: Registering an App in Entra ID
• Dynamics 365 Finance and Operations Release Notes

Got questions or need further clarification? Drop a comment below

A simple fix can make your debugging experience much smoother by disabling unnecessary sites in IIS. Here’s how to set it up so that only the AOSService process runs, eliminating the need to guess which w3wp.exe instance to reattach.

Why Multiple w3wp.exe Processes Appear

When you run D365 F&O on your local machine, several IIS sites might be up by default:

• AOSService: The main D365 F&O application service.
• RetailServer: A retail component if your environment includes it.
• RetailCloudPos: Another retail component related to Point of Sale.

For many developers who aren’t working with retail functionality, only the AOSService process is needed for debugging. Yet Visual Studio will prompt you to choose among all these w3wp processes every time, adding unnecessary friction to the debugging process.

Disabling Unnecessary IIS Sites

To avoid being prompted, you can stop the retail-related sites under IIS Manager and keep only the AOSService site running. This way, only one w3wp.exe process will spin up when the application is running, and Visual Studio will no longer ask which process to attach to.

Steps to Disable Unnecessary Sites

1. Open IIS Manager:
   • Type “IIS Manager” in your Start Menu search and open it.
2. Locate the Sites:
   • In the left-hand pane, expand your machine name, then click on “Sites” to view all the web applications hosted by IIS.
3. Stop Unneeded Sites:
   • Right-click on RetailServer and RetailCloudPos and select “Stop” for each.
   • Confirm that AOSService remains running.
4. Recycle IIS:
   • Run the following command in Command Prompt (with administrator privileges) to recycle the IIS service:

     iisreset
     

5. Reattach to Debugging in Visual Studio:
   • Now, when you go to debug, Visual Studio will detect only the single AOSService process associated with D365 F&O. No more guessing required!

Benefits of This Approach

• Saves Time: You eliminate the need to select the correct process every time, allowing for faster debugging starts.
• Less Frustration: Without needing to scroll through a list of processes, you can focus on debugging and avoid trial and error.
• Streamlined Workflow: This setup keeps your development environment lean, especially if you’re working in a non-retail environment.

By disabling the unused retail sites, you can streamline your Visual Studio debugging experience and keep your focus where it should be: on the code. Happy debugging!

When extending Microsoft’s standard code in Dynamics 365, passing contextual data down the call stack can sometimes be a challenge. While Chain of Command (CoC) makes it possible to extend standard logic, there are cases where private or non-extensible methods interrupt the flow. Previously, the ContextHelper class provided a way to manage this (see previous blog post post: Chain of Command - contextual helper class) but now I have create a more robust framework to replace it.

Introducing the New Context Helper Framework

This new framework consists of multiple classes designed to make managing contract instances easier, more flexible, and more scalable. By introducing a contract registry and factory, the framework handles the lifecycle of context objects automatically. Below are the key components of the framework:

Key Framework Classes

1. ContextContractFactoryAttribute_BET - An attribute class that defines contract types.
2. ContextContractRegistry_BET - A singleton registry that manages contract instances.
3. ContextHelper_BET - The utility class used to create and retrieve contracts.
4. IContextContract_BET - The abstract contract class that implements disposable functionality for contract lifecycle management.

ContextContractFactoryAttribute_BET

internal final class ContextContractFactoryAttribute_BET extends SysAttribute implements SysExtensionIAttribute
{
    private ClassName className;

    public void new(ClassName _className)
    {
        className = _className;
    }

    public str parmCacheKey()
    {
        return classStr(ContextContractFactoryAttribute_BET) + ';' + className;
    }

    public boolean useSingleton()
    {
        return false;
    }
}

ContextContractRegistry_BET

internal final class ContextContractRegistry_BET implements System.IDisposable
{
    private static ContextContractRegistry_BET instance;
    private Map instanceMap;

    private void init()
    {
        instanceMap = new Map(Types::Integer, Types::Class);
    }

    public static ContextContractRegistry_BET instance()
    {
        if (! instance)
        {
            instance = new ContextContractRegistry_BET();
            instance.init();
        }
        return instance;
    }

    internal void insert(IContextContract_BET _contract)
    {
        instanceMap.insert(classIdGet(_contract), _contract);
    }

    internal void remove(ClassId _classId)
    {
        instanceMap.remove(_classId);
    }

    internal boolean exists(ClassId _classId)
    {
        return instanceMap.exists(_classId);
    }

    internal IContextContract_BET lookup(ClassId _classId)
    {
        return instanceMap.lookup(_classId);
    }

    public void dispose()
    {
        if (instanceMap.empty())
        {
            instanceMap = null;
            instance = null;
        }
    }
}

ContextHelper_BET

public static class ContextHelper_BET
{
    public static IContextContract_BET getContractInstance(ClassName _className)
    {
        IContextContract_BET contract;

        ClassId classId = className2Id(_className);

        ContextContractRegistry_BET registry = ContextContractRegistry_BET::instance();
        if (registry.exists(classId))
        {
            contract = registry.lookup(classId);
        }
        
        return contract;
    }

    public static IContextContract_BET createContractInstance(ClassName _className)
    {
        return SysExtensionAppClassFactory::getClassFromSysAttribute(
            classStr(IContextContract_BET),
            new ContextContractFactoryAttribute_BET(_className)
        ) as IContextContract_BET;
    }
}

IContextContract_BET

public abstract class IContextContract_BET implements System.IDisposable
{
    protected void new()
    {
        this.registry().insert(this);
    }

    public void dispose()
    {
        ClassId classId = classIdGet(this);

        if (this.registry().exists(classId))
        {
            this.registry().remove(classId);
        }

        this.registry().dispose();
    }

    private ContextContractRegistry_BET registry()
    {
        return ContextContractRegistry_BET::instance();
    }
}

Example: Timesheet Cost Price Modification

Let’s now apply the new framework to the same timesheet cost price scenario. You want to extend the TSTimesheetTrans.setCostPrice method to allow zero cost price during a specific workflow.

Step 1: Create the Contract Class

Define a contract class that will hold the custom context (e.g., whether to allow zero cost price):

[ContextContractFactoryAttribute_BET(classStr(TSTimesheetLineValidateSubmitContract_BET))]
final class TSTimesheetLineValidateSubmitContract_BET extends IContextContract_BET
{
    private boolean allowZeroCostPrice;

    public boolean parmAllowZeroCostPrice(boolean _allowZeroCostPrice = allowZeroCostPrice)
    {
        allowZeroCostPrice = _allowZeroCostPrice;
        return allowZeroCostPrice;
    }
}

Step 2: Modify the validateSubmit Method

Extend the validateSubmit method in TSTimesheetLine to use the new ContextHelper_BET framework:

[ExtensionOf(tableStr(TSTimesheetLine))]
final class TSTimesheetLine_Extension
{
    public boolean validateSubmit(boolean _showInfolog, boolean _deleteZeroHourLines)
    {
        boolean validateSubmit;

        using (TSTimesheetLineValidateSubmitContract_BET contract = ContextHelper_BET::createContractInstance(classStr(TSTimesheetLineValidateSubmitContract_BET)))
        {
            contract.parmAllowZeroCostPrice(true);

            validateSubmit = next validateSubmit(_showInfolog, _deleteZeroHourLines);
        }

        return validateSubmit;
    }
}

Step 3: Modify the setCostPrice Method

Finally, extend the setCostPrice method in TSTimesheetTrans to check the contract and set the cost price to zero if applicable:

[ExtensionOf(tableStr(TSTimesheetTrans))]
final class TSTimesheetTransTable_Extension
{
    public void setCostPrice(TSTimesheetLine _timesheetLine)
    {
        boolean origCostPriceIsZero = this.CostPrice == 0;

        next setCostPrice(_timesheetLine);

        if (origCostPriceIsZero)
        {
            TSTimesheetLineValidateSubmitContract_BET contract = ContextHelper_BET::getContractInstance(classStr(TSTimesheetLineValidateSubmitContract_BET));

            if (contract && contract.parmAllowZeroCostPrice())
            {
                this.CostPrice = 0;
            }
        }
    }
}

Summary

The new ContextHelper_BET framework simplifies the handling of contextual data within Chain of Command scenarios by using a contract registry and a factory to manage the lifecycle of context objects. It is more flexible and scalable than the previous implementation, allowing you to easily extend methods while maintaining the integrity of the call stack.

This framework is ideal for complex extensions where non-extensible objects or methods interrupt the flow of contextual data. However, as always, use this approach judiciously to avoid unnecessary complexity in your codebase.

In this post, I’ll walk through an example of how to replace deep links with a LinkHandler class.

The Concept Behind LinkHandler

The LinkHandler class serves as a more dynamic and maintainable alternative to deep links. It takes URL parameters—such as a table name and a search key—and attempts to locate the corresponding record. Once the record is found, it redirects the user to the relevant form.

This method is more flexible than traditional deep links because it decouples the URL structure from specific record identifiers, making the system more resilient to changes.

Key Features of the LinkHandler Approach

• Dynamic Record Search: The handler uses the table name and search key passed in the URL to query for the correct record.
• Error Handling: If no record is found, the user is alerted with a meaningful error message.
• Automatic Redirection: Once the record is found, the handler redirects the user to the appropriate UI form.
• Security Compliance: Before redirection, the handler ensures that the user has the necessary permissions to view the record.

Building the URL for the LinkHandler

To use the LinkHandler class, you’ll need to construct the URL with the appropriate query parameters. Below is the template format and a real usage example. Note that an appropriate MenuItemAction should be created and secured through a priviliege.

URL Template

&mi=action:LinkHandler&tableName=[TableName]&searchKey=[Field1:Value1];[Field2:Value2];[...]

• tableName: The name of the table you want to search.
• searchKey: A semicolon-separated list of field-value pairs used to locate the record.

Real Usage Example

&mi=action:LinkHandler&tableName=ProjTable&searchKey=ProjId:PRJ-000032

In this example, the LinkHandler searches the ProjTable for a record where the ProjId is PRJ-000032.

Code Example: LinkHandler

Below is the X++ implementation of the LinkHandler class.

internal final class LinkHandler
{
    private TableName tableName;
    private container searchKey;
    private Common common;

    public static LinkHandler construct()
    {
        return new LinkHandler();
    }

    public static void main(Args _args)
    {
        var linkHandler = LinkHandler::construct();
        linkHandler.initFromUrl();
        linkHandler.redirect();
    }

    private void initFromUrl()
    {
        URLUtility urlUtility = new URLUtility();

        tableName = urlUtility.getQueryParamValue('tableName');
        searchKey = str2con(urlUtility.getQueryParamValue('searchKey'), ';');
    }

    private Common fetchRecord()
    {
        SysDictTable entityDictTable = SysDictTable::newName(tableName);
        common = entityDictTable.makeRecord();

        var searchObject = this.getSearchObject(common);
        var searchStatement = new SysDaSearchStatement();

        if (!searchStatement.findNext(searchObject))
        {
            throw error('No record found.');
        }

        return common;
    }

    private SysDaSearchObject getSearchObject(Common _common)
    {
        var queryObject = new SysDaQueryObject(_common);
        SysDaEqualsExpression equalsExpression;

        for (int i = 1; i <= conLen(searchKey); i++)
        {
            str keyValue = conPeek(searchKey, 1);
            str fieldName, value;
            [fieldName, value] = str2con(keyValue, ':');

            SysDictField dictField = SysDictField::newName(tableId2Name(_common.TableId), fieldName);

            if (!dictField)
            {
                throw error(strFmt('Unknown field %1', fieldName));
            }

            anytype searchValue = this.getSearchFieldValue(value, dictField);

            if (!equalsExpression)
            {
                equalsExpression = new SysDaEqualsExpression(
                    new SysDaFieldExpression(_common, fieldName),
                    new SysDaValueExpression(searchValue)
                );
            }
            else
            {
                equalsExpression.and(
                    new SysDaEqualsExpression(
                        new SysDaFieldExpression(_common, fieldName),
                        new SysDaValueExpression(searchValue)
                    )
                );
            }
        }

        if (equalsExpression)
        {
            queryObject.whereClause(equalsExpression);
        }

        queryObject.firstOnlyHint = SysDaFirstOnlyHint::FirstOnly1;
        return new SysDaSearchObject(queryObject);
    }

    private anytype getSearchFieldValue(anytype _value, SysDictField _dictField)
    {
        Types type = _dictField.baseType();

        switch (type)
        {
            case Types::RString:
            case Types::VarString:
            case Types::String:
                return any2Str(_value);
            case Types::Integer:
                return any2Int(_value);
            case Types::Int64:
                return any2Int64(_value);
            case Types::Real:
                return any2Real(_value);
            case Types::Date:
                return any2Date(_value);
            case Types::Enum:
                return new SysDictEnum(_dictField.enumId()).name2Value(_value);
            case Types::Guid:
                return any2Guid(_value);
            case Types::UtcDateTime:
                return DateTimeUtil::parse(_value);
            default:
                throw error(strfmt("@SYS73815", type));
        }
        return null;
    }

    private void redirect()
    {
        SysDictTable entityDictTable = SysDictTable::newName(tableName);
        Common record = this.fetchRecord();

        var accessRights = SecurityRights::construct().tableAccessRight(entityDictTable.name(), record);

        if (accessRights == AccessRight::NoAccess)
        {
            throw error('Insufficient rights to access record');
        }

        Args args = new Args(entityDictTable.formRef());
        args.record(record);

        FormRun formRun = classfactory.formRunClass(args);
        formRun.init();
        formRun.run();
        formRun.detach();
    }
}

Optimizing URL Parameters with Standardization

While the current LinkHandler URL structure works, we can take inspiration from the OData protocol to make the URL parameters more standardized and readable. By following a convention similar to OData query syntax, we can make the URLs more intuitive and easier to parse.

OData-Inspired URL Structure

In OData, query parameters are standardized, allowing for more flexibility and clarity when querying data. For instance, we can use parameter names like $filter to specify conditions in a consistent way. Here’s how we could apply this approach to our LinkHandler class:

Optimized URL Template

&$table=TableName&$filter=Field1 eq 'Value1' and Field2 eq 'Value2'

• $table: Specifies the table to search.
• $filter: Defines the conditions for locating the record, similar to OData filters. Using eq (equals) allows for better clarity and alignment with standard query syntax.

Real Usage Example

&$table=ProjTable&$filter=ProjId eq 'PRJ-000032'

In this example, we search the ProjTable for a record where ProjId equals PRJ-000032. The use of $filter allows for potential expansion in the future, such as supporting other operators (ne for “not equal,” gt for “greater than,” etc.).

Benefits of Standardization

1. Clarity: The URL becomes more readable and easier to understand for both developers and administrators.
2. Flexibility: By using a standardized format, we can expand the logic to support more complex queries in the future without breaking existing URLs.
3. Maintainability: Standardized URLs are easier to maintain as they follow a known convention, reducing the risk of errors.

Standardizing the URL parameters not only aligns with best practices but also makes the solution scalable and easier to integrate with other parts of the system. But since this was more of a proof of concept, I decided to just use an easier approach to implement the URL parameter handling.