How to Install Docentric AX Framework via XPO Files

The goal of this tutorial is to guide you through the installation of Docentric AX Framework via XPO files.

Alternatively, you can also install Docentric AX Framework via model. Learn how >>

It is recommended to install the product in an upper layer in case that we are installing the product for the evaluation purpose. This way the product can be easily removed (by removing the whole layer) after the evaluation has ended.

On the other hand the licensed product should be installed on ISV/VAR/CUS layer; that depends on your strategy.

Current version of Docentric AX Framework supports AX 2012 R2 and R3 versions.

1. Set the current layer to the USP layer

Let’s say we are installing Docentric AX Framework in the USP layer. We need to switch the current application object layer to the USP layer for your AX client to open. Run Microsoft Dynamics AX 2012 Configuration in Control Panel/System and Security/Administrative Tools.

The Microsoft Dynamics AX Configuration Utility form is opened. On the Developer tab set Application object layer to open to USP.

You can read more on how to set the application object layer here.

2. Check if the USP layer already contains objects

Before we proceed we might want to check if there are existing objects in the USP layer so that in the end of the evaluation we can remove the whole layer.

Open the AX client (now in the USP layer) and run the job below.

static void ObjectsInCurrentLayer(Args _args)
{
    #SysVersionControl
	
    UtilEntryLevel  curLayer    = currentAOLayer();
    modelId         curModelId  = xInfo::getCurrentModelId();
    str             modelName = SysModelStore::modelId2Name(curModelId);

    SysModelElementData elemData, parentData;
    SysModelElement     parent, child;
    TreeNode            pNode, cNode;


    setPrefix('All artifacts in current layer');

    // Set options to skip cache lookup of file names
    infolog.globalCache().set(#VCSCache, #NoPrompt,true);

    while select RootModelElement from child
        group by child.RootModelElement, elemData.ModelId
        join ModelId from elemData
            where elemData.ModelElement == child.RecId
                // Layer numbers in SysModel* views are offset by +1
                && elemData.Layer       == (curLayer + 1)
                // Remove the following line to include all models
                && elemData.ModelId     == curModelId
    {
        // Get lowest layer copy of parent
        select firstOnly parent
            order by parentData.Layer
                where parent.RecId == child.RootModelElement
            join parentData
                where parentData.ModelElement == parent.RecId;

        pNode = SysTreeNode::findNodeInLayer(
                      parent.ElementType, parent.name, 0, parentData.Layer - 1);
        if(!pNode)
            continue;

        if (pNode.AOTLayer() == curLayer)
        {
            info(strfmt("%1 %2",pNode.treeNodePath(), modelName));
        }
    }
}

static void ObjectsInCurrentLayer(Args _args)

{

#SysVersionControl

UtilEntryLevel curLayer = currentAOLayer();

modelId curModelId = xInfo::getCurrentModelId();

str modelName = SysModelStore::modelId2Name(curModelId);

SysModelElementData elemData, parentData;

SysModelElement parent, child;

TreeNode pNode, cNode;

setPrefix('All artifacts in current layer');

// Set options to skip cache lookup of file names

infolog.globalCache().set(#VCSCache, #NoPrompt,true);

while select RootModelElement from child

group by child.RootModelElement, elemData.ModelId

join ModelId from elemData

where elemData.ModelElement == child.RecId

// Layer numbers in SysModel* views are offset by +1

&& elemData.Layer == (curLayer + 1)

// Remove the following line to include all models

&& elemData.ModelId == curModelId

{

// Get lowest layer copy of parent

select firstOnly parent

order by parentData.Layer

where parent.RecId == child.RootModelElement

join parentData

where parentData.ModelElement == parent.RecId;

pNode = SysTreeNode::findNodeInLayer(

parent.ElementType, parent.name, 0, parentData.Layer - 1);

if(!pNode)

continue;

if (pNode.AOTLayer() == curLayer)

{

info(strfmt("%1 %2",pNode.treeNodePath(), modelName));

}

Job_ObjectsInCurrentLayer.xpo

After the job is executed we will get the list of all objects that exist in the USP layer.

3. Import the Docentric_NewArtifacts project

After the pre-preparation steps have been completed, we can go to the next step: importing the project containing all new artifacts of Docentric AX Framework.

Docentric AX Framework consists mainly of completely new AX artifacts that are AX version independent, i.e. work for both AX 2012 R2 and R3 versions. They are included in the Docentric_NewArtifacts project. However some of the built-in artifacts are modified and included in Docentric AX Framework as well, primarily to enable enhancement of SSRS reports and Document Template Libraries. Since they differ from R2 to R3 versions, an AX version specific project (Docentric_ChangedArtifacts) containing all the modified built-in artifacts is introduced. We are going to import this project later.

Click the Import button of an AOT window and select from the downloaded DocentricAX_xx.zip package the Docentric_NewArtifacts_AX2012_R2_R3.xpo file which contains the Docentric_NewArtifacts project.

After the project has been imported a significant number of the compilation errors will be reported.

We have to import the same project once again, because not all the artifacts have been imported successfully in the first time.

During the re-import of the Docentric_NewArtifacts project click the Yes to all button when the confirmation message box pop ups.

After the second import, the number of compile errors decreases. Among others Variable Docentric has not been declared errors will appear.

These errors will be removed after two Visual Studio projects within the Docentric_NewArtifacts project are deployed.

4. Deploy Visual Studio projects

In the Docentric_NewArtifacts project there are two Visual Studio projects: DocentricUtilities and DocentricServiceProxy.

Navigate to DocentricUtilities in the Visual Studio CSharp Projects node and click Edit within the contextual menu.

The DocentricUtilities C# project opens in Visual Studio. Rebuild and deploy the project.

At this point, two errors are possible. Deployment can be successfully performed if no AX client and AOS are running. We should close the AX client application and stop the AOS service or, alternatively, we can enable hot-swapping of assemblies for our AOS instance.

Enabling the hot-swapping of assemblies for AOS

Run Microsoft Dynamics AX 2012 Server Configuration in Control Panel/System and Security/Administrative Tools.

The Microsoft Dynamics AX Server Configuration Utility form opens. On the Application Object Server tab check the Enable the hot-swapping of assemblies for each development session checkbox.

By clicking the OK button the AOS service will be restarted.

You can read more on how to enable hot-swapping assemblies here .

After we have closed the AX client application and stopped the AOS service / enableed hot-swapping assemblies, return to the DocentricUtilities and DocentricServiceProxy Visual Studio projects, rebuild and deploy them.

The Deploy to Client and Deploy to Server project properties have to be set to Yes.

Repeat rebuild and deploy procedure for the second project (the project order is not important).

Open the AX client application. Compile the Docentric_NewArtifacts project. If the Variable Docentric has not been declared error persists, generate incremental CIL and restart the AOS service. The rest of the compilation errors are related to built-in artifacts affected by Docentric AX Framework.

The next step is the import of the Docentric_ChangedArtifacts project containing all the built-in artifacts that are modified by Docentric AX Framework in order to enable integration with built-in SSRS and Document Template Libraries frameworks.

5. Import the Docentric_ChangedArtifacts project

Click the Import button of an AOT window and select from the downloaded DocentricAX_xx.zip package:

the Docentric_ChangedArtifacts_AX2012_R3_CU13.xpo file, if you have AX 2012 R3 CU13,
the Docentric_ChangedArtifacts_AX2012_R3_CU12.xpo file, if you have AX 2012 R3 CU12,
the Docentric_ChangedArtifacts_AX2012_R3_CU11.xpo file, if you have AX 2012 R3 CU11,
the Docentric_ChangedArtifacts_AX2012_R3_CU10.xpo file, if you have AX 2012 R3 CU10,
the Docentric_ChangedArtifacts_AX2012_R3_CU9.xpo file, if you have AX 2012 R3 CU9,
the Docentric_ChangedArtifacts_AX2012_R2_CU8_CU9.xpo file, if you have AX 2012 R2 CU8 or CU9, or
the Docentric_ChangedArtifacts_AX2012_R2_CU7.xpo file in case you have AX 2012 R2 CU7.

If you have AX 2012 R2 version with CUx less than CU7 or AX 2012 R3 version with CUx less than CU9, please contact us to provide you the suitable version of the Docentric_ChangedArtifacts project.

The Docentric_ChangedArtifacts_AX2012_Rx_CUx.xpo file contains the Docentric_ChangedArtifacts project which is AX version dependent. For each artifact from the list you can click the Compare button to see the differences between the original and the modified artifact. You can always compare and merge the artifacts later, after the import.

Click the Yes to all button in the message confirmation box.

If you have also changed the built-in artifacts affected by Docentric AX Framework, then you have to compare and merge your changes back into the imported artifacts. This can especially be the case with the SystemAdministration menu, and with the following security artifacts: the SysServerITManager role, the SysServerIT process cycle and the SysServerAXBasicMaintain duty.

Except these four artifacts any of the remaining project artifacts can potentially be changed by both your company and Docentric AX Framework.

It is recommended to select each of the artifacts in the Docentric_ChangedArtifacts project and compare, review and merge changes if the artifact is an overlapped/conflicted artifact.

If you are installing the licensed product in your ISV/VAR/CUS layer and you use TFS as a Source Version Control tool, then you will first have to check them out.

6. Import Docentric labels

We have to create at least two Docentric AX label files: an AX label file for the EN-US language and an AX label file for the current AX client language. Let’s say that the (one of) AX client language(s) is a Dutch language. First we will create a new AX label file for the EN-US language named as DOC, from the AxDOCen-us.ald text file.

Select the Label Files node in the AOT and click the Create from File contextual menu item.

Select the AxDOCen-us.ald file and click the Open button.

We have successfully imported the DOC label file for the EN-US language.

Now, we want to import the label file for the Dutch language (NL). Copy the AxDOCen-us.ald file and rename it to AxDOCnl.ald.

Repeat the import of the AxDOCnl.ald file as an AX label file.

The result is shown on the figure below.

If you want to customize Docentric AX product for a language different than English you will have to translate all Docentric labels to the desired language.

You don't have to translate the labels to your language(s) right away, i.e. upfront, but you can do it gradually, label by label, leaving the diagnostic messages for the end. Labels which are not yet translated to your language(s) will appear in the English language.

Importing Docentric labels for both EN-US and the current AX client language is a mandatory step in the installation process. Otherwise none of the diagnostic messages, i.e. messages from the code will not be shown properly. They will appear as empty strings, not even shown in the alternate help language, as it is the case with labels on forms.

7. Import the Docentric project

This project is suitable for exploring Docentric AX Framework. Click the Import button of an AOT window and select from the downloaded DocentricAX_xx.zip package the Docentric_AX2012_R2_R3 project. Click the Show details checkbox. You can see that the project contains only project definition, i.e. the Docentric project.

Open the imported project and compile it.

The Docentric project have to be compiled with no error. If there is an error re-import the Docentric_NewArtifacts and Docentric_ChangedArtifacts projects again.

8. The last step

The last step is to synchronize all tables from the Docentric_NewArtifacts and Docentric_ChangedArtifacts projects. Afterwards generate incremental CIL and restart the AOS service. If you have some problems with Print Management report execution, full compile and generating full CIL might be required.

CONTENTS

How to Install Docentric AX Framework via XPO Files

IN THIS ARTICLE

1. Set the current layer to the USP layer

2. Check if the USP layer already contains objects

3. Import the Docentric_NewArtifacts project

4. Deploy Visual Studio projects

Enabling the hot-swapping of assemblies for AOS

5. Import the Docentric_ChangedArtifacts project

6. Import Docentric labels

7. Import the Docentric project

8. The last step

See also

IN THIS ARTICLE