CONTENTS
X

How to Add Docentric AX Models to TFS/Azure DevOps

IN THIS ARTICLE
Azure DevOps is a new name for TFS Online. In this manual we use the term TFS.

Learn which Docentric AX models are available and which models to install >>

Docentric AX SSRS Replicas and optional models Docentric AX License Plate Labels and Docentric AX CBD Replicas are not covered by this manual but the approach of adding their artifacts to TFS is the same as for the typical models such as Docentric AX Extension and Docentric AX Emails; the Docentric AX model is specific because of the additional DLL file(s).

Clean installation: Add regular model artifacts to TFS

After you import these models using the script or the ModelUtil command line tool (see How to Install Docentric AX via Models) and then open Windows Explorer, you will notice in <ServiceNode>:\AOSService\PackagesLocalDirectory three new folders. These folders represent so called AX packages and in case of the Docentric AX product each of them contains exactly one model:

All artifacts from the marked folders on the image below should be added to TFS version control.

In each of the Descriptor folders you will find the single model descriptor file, whereas DocentricAX\Docentric AX, DocentricAXExtension\Docentric AX Extension, DocentricAXEmails\Docentric AX Emails contain all model’s source files. They are XML files and contain definitions of Docentric classes, forms, tables, etc. as well as extensions of the built-in D365FO artifacts. These artifacts should all be added to TFS version control.

 

The Docentric AX model ships with additional libraries (DLLs) installed in the DocentricAX\bin folder, which contain the document rendering engine and helper C# libraries. These DLL files will appear in the DocentricAX\bin folder after the Docentric AX model is installed and they should also be added to TFS as described below.

The Docentric AX model from version 3.3.9 contains only one additional DLL. For previous versions (3.3.8 or below), it contains three DLLs. They will appear in the DocentricAX\bin folder and should be added to TFS.

Clean installation: Add DLLs to TFS for 3.3.9 or above

For version 3.3.9 or above, all Docentric DLL files are merged into single one named Docentric.AX.dll. This DLL should be added to TFS.

From the Docentric AX\bin folder, add to TFS only Docentric.AX.dll. All other files, which will be created in this folder after the first build, including Dynamics.AX.DocentricAX.dll, are the build artifacts and should not be added to TFS.

Clean installation: Add DLLs to TFS for 3.3.8 or below

For version 3.3.8 or below, the Docentric AX model contains three DLLs that should be added to TFS:

  • Docentric.Documents.dll
  • Docentric.Dynamics.AX.dll
  • Microsoft.ApplicationInsights.dll

These three DLLs: Docentric.Documents.dll, Docentric.Dynamics.AX.dll and Microsoft.ApplicationInsights.dll from the Docentric AX\bin folder should be added to TFS version control.

Upgrade installation: Commit changes to TFS

After you replace Docentric AX models, the model folders and descriptor files will be automatically updated. New files will be added and old ones removed, except Docentric DLL files in the bin folder of the DocentricAX package, where the old files remain.

When you check-in the upgraded version to TFS, there should be exactly the same files in repository as if you would install and check-in the new version on a clean environment. TFS does not automatically detect and include all upgrade changes for check-in. It requires some manual steps that can be error prone.

If you would like to check-in all the changes of the upgraded Docentric models, make sure all these changes are listed in Team Explorer\Included Changes, before checking-in them to TFS. Updates are included automatically, while deleted files have to be manually promoted from Team Explorer\Excluded Changes > Detected. New files have to be added manually as well (Add Items to Folder). Obsolete Docentric DLLs in DocentricAX\bin folder have to be manually deleted.

Therefore, we recommend the following, more reliable UPGRADE PROCEDURE:

  1. Stop IIS (or IIS Express) and the Batch service.
  2. Delete all Docentric AX models (i.e. packages) from TFS and check-in the changes.

     

    DO NOT delete DocentricAXSSRSReplicas if you customized them, neither any other customization of Docentric AX models you might have.
  3. Delete the Docentric AX package folders from the disk:
    • AOSService\PackagesLocalDirectory\DocentricAX
    • AOSService\PackagesLocalDirectory\DocentricAXExtension
    • AOSService\PackagesLocalDirectory\DocentricAXEmails
    • AOSService\PackagesLocalDirectory\DocentricAXSSRSReplicas - DO NOT delete if you customized the replicas!
    DO NOT compile or synchronize the database at this point.
  4. Since we deleted the Docentric AX models, you can actually import the latest version of the models by using ModelUtil.exe (modelutil -import) as it goes for the clean installation, or you can still replace them by using use the replace command (modelutil -replace).
    Alternatively, you can use DocentricAXInstallCoreModels.cmd and DocentricAXInstallSSRSReplicasModel.cmd to import/replace the models.
  5. Add the regular artifacts from Docentric AX models to TFS as described in the above chapter. Make sure that the correct DLLs from the DocentricAX\bin folder are added to TFS.
  6. Check-in the changes and verify on the TFS (Azure DevOps) portal that you really have the right code in place in the repository.
  7. Build the Docentric AX models.
  8. Synchronize the database.
    Alternatively, you can use DocentricAXBuildAndSyncTool.cmd to build the models and synchronize the database.
  9. Start IIS (or IIS Express) and the Batch service.
It is of key importance that you DO NOT synchronize the database before the new models are installed and built, and that application is stopped during the upgrade procedure (IIS and the Batch service). Violation of this rule might result in loss of your data!

After building Docentric AX models

After building Docentric AX core models, the bin folder will be created for the DocentricAXExtension and DocentricAXEmails packages, whereas the bin folder of the DocentricAX package is created immediately after the import of the Docentric AX model, and it contains Docentric DLL(s).

After the build, all bin folders will be filled with Microsoft’s DLLs and other files, so bear in mind that only Docentric DLL(s) from the screenshots below (and specified in the above chapters) should be put under TFS version control.

If you put any other files from the bin folder of the DocentricAX package under TFS, you will see the changed objects in Pending changes after each build.

 

See also

How to Unlock the Product >>
How to Install Docentric AX Designer >>
How to Set Up Docentric AX >>

IN THIS ARTICLE