Tracing

With the Docentric Tracing framework you can trace:

  • SSRS and Docentric report execution,
  • Posting and printing process,
  • Loading Print management settings,
  • Printing reports via DRA,
  • Alert notifications.

Tracing is by default disabled. You can turn it on by Trace category or Trace action. Trace categories and Trace actions map more or less to above listed functionalities.

Tracing, when enabled for a particular Trace category, collects useful information whenever a supported Trace event occurs so you can review and analyze it later.
Collected tracing data is saved to all enabled Trace destinations. Currently, two types of Trace destinations are supported: Infolog and Database – more specifically, the DocTraceTable table.

On the other hand, when tracing is enabled for a particular Trace action, it usually performs that action (for example, dumping a Docentric template), and it is not affected by Trace destinations nor Trace events.

Trace categories, Trace destinations and Trace actions are different types of Trace parameters.
Trace parameters are configured in the DocTraceParam table.

How to set up Trace parameters

Trace parameters can be configured in the DocTraceParam table.

The DocTraceParam table can be edited in non-development environments using a special menu item DocTraceParam, i.e. via the link:
https://usnconeboxax1aos.cloud.onebox.dynamics.com/?mi=DocTraceParam
(NOTE: the first part of the address is environment-specific).

The DocTraceParam menu item opens Docentric Table Browser which is the same as the built-in Table Browser except for one thing: it enables editing of Docentric system tables such as DocTraceParam and DocentricEngineSetting in non-development environments for users with the Docentric AX Administrator role. Learn more >>

The DocTraceParam table has a smart logic when adding new Trace parameters.

Add a new trace parameter by clicking New and then click Save before adding the next one. Repeating this procedure will eventually add all available parameters.
Trace parameters are disabled by default. To enable them, the Parameter value field must be set to Enable.

Of course, Trace parameters can also be added manually by entering Parameter name and Parameter value.

The following Trace parameters are supported:

  • Trace destinations:
    • TraceToDatabase
    • TraceToInfolog
  • Trace categories:
    • SSRS
    • DOCENTRIC
    • REPORT_EXEC_TIMES
    • POSTING
    • POSTING_PRINT
    • PRINTMGMT
    • ALERTS
  • Trace actions:
    • TraceDDSP
    • TraceDocentricTemplate
    • TraceGeneratedDocument
    • DRADocument

Trace destinations

There are two Trace destinations where tracing information can be stored:

  • Database, where all tracing information is saved to the DocTraceTable table. Tracing to database is enabled if the TraceToDatabase trace parameter has value Enable.

  • Infolog, where tracing information is displayed in Infolog (Message bar or Action center). Tracing to Infolog is enabled if the TraceToInfolog trace parameter has value Enable.

While it may be handier to have tracing information stored in the database due to the filtering and sorting ability, seeing information directly in Infolog can quicker give you some answers. Of course, both options can be used at the same time.

The fields in the DocTraceTable table:

  • System fields: CompanyId, UserId, ThreadId, SessionId, BatchJobId, BatchJobTaskId.
  • TraceCategory, e.g. SSRS, DOCENTRIC, PRINTMGMT, ALERTS.
  • TraceEvent, e.g. START, END, ON_PRINTMGMT_LOAD, NOTIFICATION_CREATED.
  • MessageSeverity, e.g. Info, Warning, Error.
  • Message, e.g. SSRS report design name, Alert table name, Journal table name.
  • TraceContextInfo1 .. TraceContextInfo7: fields with context information depending on Trace category and Trace event, e.g. print settings, target print destination, template ID, report parameters, execution IDs.

Trace SSRS and Docentric report execution

Now that we enabled tracing to both trace destinations - Infolog and Database, we can trace report execution by enabling the SSRS and DOCENTRIC trace parameters:

  • SSRS will trace an SSRS report execution to any SSRS print destination except the standard Screen destination. It works also when printing reports via Docentric print destinations, since the initial part of the pipeline is always the SSRS pipeline.
  • DOCENTRIC will trace report execution only if a Docentric print destination is used. This also includes redirections from SSRS Screen to Docentric Screen, triggered by the Use Docentric design and viewer flags in Docentric report setup. Learn more about this redirection >>
When an error occurs during printing a report to a Docentric print destination, use the SSRS and DOCENTRIC trace parameters to check if Docentric pipeline was executed at all, what was the target print destination, Template ID, report parameters, Pre-processed Id, Report run Id, etc.

To test the SSRS and DOCENTRIC trace parameters, we will print an invoice from (Customer) Invoice journal. Configure Print management setup to print Customer invoices to Docentric Email, open Invoice journal and click the Invoice tab > Document > View > Use print management.
Tracing information will appear in both Infolog and the DocTraceTable table.

 

You can match the records for the SSRS and DOCENTRIC categories with the ON_PRINT_REPORT, START and END trace events that are sourced from the execution of the same report by using the ReportRunId value stored in the TraceContextInfo1 column of the DocTraceTable table.

Trace report execution times

From 3.4.4 version, you can trace report execution times, for now only for reports executed via Docentric print destinations. This includes reports generated using both Docentric templates and SSRS report designs. In Trace parameters enable the REPORT_EXEC_TIMES trace category as well as tracing to Infolog and database (the DocTraceTable table) to see the tracing results.

Currently, there is a single trace event - EXEC_COMPLETED, which occurs when a report execution completes, with three report execution times logged:

  • dspClass = the report DSP class execution time. DSP class is responsible for creating the report DDSP (data source) but also for handling placeholders used in print destination settings, loading additional report attachments (e.g. for emailing) and processing SharePoint metadata. Note that pre-processed reports such as Sales invoice already have the data prepared once their DSP class is executed, while regular and query-based reports don’t, so for such reports the DSP class will actually perform the data fetching. Thus, the duration of a DSP class execution also depends on the report type.
  • docGen = document generation time in the target output format (PDF, Word, Excel, EMF). This covers document generation using both Docentric Document Generator and SSRS Reporting Services, if the target print destination is a Docentric destination. Document generation time includes also applying electronic signature, if configured so.
  • total = dspClass + docGen + report distribution time. Report distribution time is time spent on emailing, saving to Azure Blob storage, etc., depending on the target print destination settings. Report distribution time includes also document encryption and saving to Print archive, if configured so.

 

In one of the future releases, we will add more fine-grained measurements regarding DDSP generation, document signing and report distribution methods as well as collect execution times before the Docentric pipeline starts. Namely, the latter would be useful to measure the duration of data fetching for common reports such as Sales invoice or Purchase order, since they are pre-processed reports and this measurement is not included in the dspClass execution time.

You can match the records for the SSRS, DOCENTRIC and REPORT_EXEC_TIMES categories that are sourced from the execution of the same report by using the ReportRunId value stored in the TraceContextInfo1 column of the DocTraceTable table.

Trace posting and printing

We can also benefit from tracing when it comes to posting-and-printing related issues. The relevant trace parameters are:

  • POSTING, which will trace posting transaction starts and ends.
  • POSTING_PRINT, which will trace printing in the posting process.
When an error occurs while posting and printing multiple documents in batch, use the POSTING and POSTING_PRINT trace parameters to detect if the error occurred during the posting or printing, if the printing error affected the posting, etc.

When posting multiple documents (e.g. sales orders), the reports can be posted and printed one-by-one, or all of them can be posted first and then printed. This behavior depends on the Print options configured on the posting dialog (Current and After), please see the image below. It’s important to understand this because a printing error in batch will terminate the batch job and the rest of the documents will not get processed (posted-and-printed for Current or printed for After).

To test this, go to All sales orders and post in batch at least two invoices by selecting Generate > Invoice.
On the posting dialog, if we set Printing parameters > Print options > Print to:

  • After, the printing will take place after the posting of all documents. Trace will look like this: POSTING trace for all documents first, then POSTING_PRINT trace at the end.

  • Current, each document will be printed separately after the posting and before the next document is posted. Trace will look like this: POSTING and POSTING_PRINT traces are triggered separately for each document.

Current works only when posting documents in batch, otherwise system automatically switches to After.

Trace Print management

Next is the PRINTMGMT parameter, which traces the Print management framework when printing reports with Print management preview or Use print management options.

When Print management settings are different than you expect (e.g. you have a bunch of customer/vendor overrides), use the PRINTMGMT trace parameter to detect which Print management setting exactly was loaded and used to print the report.

We can test the PRINTMGMT parameter by opening the (Customer) Invoice journal and go to Document > View > Use print management to print the selected invoice.

When printing is executed, we will see a trace with the Event name=ON_PRINTMGMT_LOAD and Trace category=PRINTMGMT.

The trace message in Infolog:

The trace record in the DocTraceTable table in the database:

It contains more useful information than Infolog, such as Name of the used print management setting, the target print destination, number of copies and if exists, the condition query based on which this print management setting was selected for printing the report.

Learn how to configure Print management tracing in greater detail >>

Trace cloud printing (DRA)

The DRADocument trace parameter is a little bit different from the rest since it does not store the traces to Infolog or the database. Instead, it will enable us to see the content of the document sent to a Network printer by dumping all involved files in the browser.

Use the DRADocument trace parameter if the report generated in D365FO (e.g. previewed in Docentric Viewer) differs from the document printed on the selected network printer in terms of margins, paper size, orientation, fonts, etc.

To test this, we will print a document to a network printer using Docentric Printer print destination. The files uploaded in the cloud that will later be fetched and printed locally by Document Routing Agent (DRA) will also be downloaded to the browser.

The download consists of a single XML file (with printing information such as margins and orientation, one per document) and multiple EMF files (document content, one per page).

You can open and investigate these files to check if the files sent to the printer are correct.
Learn more >>

Trace report generation

From the 3.4.5 version on, you can trace report generation by dumping the following report execution files in the browser:

  • Runtime DDSP file - if the trace parameter TraceDDSP is set to the value Enable. Dumping is done for reports generated from both Docentric templates and SSRS report designs.
  • Used Docentric template (a Word document) - if the trace parameter TraceDocentricTemplate is set to the value Enable. Dumping is done only for reports generated from Docentric templates.
  • Generated report file (in the selected output format) - if the trace parameter TraceGeneratedDocument is set to the value Enable. Dumping is done for reports generated from both Docentric templates and SSRS report designs.

 

Dumping of report execution files: a runtime DDSP, used Docentric template and generated document is supported only when the report is printed via a Docentric print destination. Dumping in batch is not supported.

Once in the future, we will support dumping to the database or Azure Blob storage, which will enable dumping report execution files also in batch.

Use the trace parameter:
(1) TraceDDSP to dump the runtime DDSP file if you need to troubleshoot document generation based on Docentric templates or resolving placeholders in print settings.
(2) TraceDocentricTemplate to confirm which Docentric template exactly is used for document generation.
(3) TraceGeneratedDocument to troubleshoot document generation based on both Docentric templates and SSRS report designs.

Docentric print destinations that are not (fully) supported

  • When printing to Generate DS print destination, dumping of report execution files IS NOT SUPPORTED.
  • Docentric Printer print destination limitations:
    • When printing to Docentric Printer print destination on premises, dumping of report execution files IS NOT SUPPORTED.
    • When printing to Docentric Printer print destination in cloud with Print as PDF turned off, dumping of generated documents IS NOT SUPPORTED, while dumping of runtime DDSP files and Docentric templates IS SUPPORTED. In that case, please use the trace parameter DRADocument. Learn more >>
    • When printing to Docentric Printer print destination in cloud with the Print as PDF option turned on, dumping of report execution files IS SUPPORTED.
  • For tracing report execution files when printing to Docentric Memory print destination, the additional trace parameter TraceGeneratedDocumentInMemory should be enabled.

Runtime DDSP

Unlike design-time DDSP, which is generated via Docentric Generate DS print destination or by enabling DDSP generation in Docentric report setup, the runtime DDSP does not contain data source schema nor translations for all selected preview languages. Also, because the report DSP class might use a switch for runtime mode, it can happen the resulting report data differs in design-time and runtime DDSP files.

Trace alerts

We can also trace alert notifications and alert notification emails by enabling the ALERTS trace parameter.
This will trace two events:

  • NOTIFICATION_CREATED - when an alert is triggered.
  • DOCENTRIC_EMAILING - when an alert notification email is sent using Docentric, which happens if the Sent email using Docentric option on the corresponding alert rule is turned on. Learn more >>
If you receive an alert notification in Action center but you don’t receive the alert notification email, use the ALERTS trace parameter to check whether the alert email should have been sent by the system, by Docentric, or it shouldn’t have been sent at all.

In the case that an alert email should have been sent by Docentric, additional information on email processing (Batch email sending status), email sender and recipients will be logged in DocTraceTable as well as the error message, if any.

Let's create an alert rule by clicking Create a custom alert on the All purchase orders form (PurchTableListPage) to get an alert whenever the Warehouse field is changed:

Now, changing the Warehouse field will be creating alert notifications. Each time an alert notification is created, the NOTIFICATION_CREATED event will be traced.

Additionally, if the alert rule is configured with the Sent email using Docentric option turned on, the DOCENTRIC_EMAILING events will also be traced each time when an alert notification email is sent.

Note that you can pair the records with the NOTIFICATION_CREATED and DOCENTRIC_EMAILING trace events by using the EventInboxId value stored in the TraceContextInfo1 column of the DocTraceTable table.

Tracing for Alert summary emails is supported by the same trace category (ALERTS) and trace events (NOTIFICATION_CREATED and DOCENTRIC_EMAILING).

See also

Diagnostic Console >>
Trace HTTPS Requests and Responses in D365FO >>
Figure out your D365FO Print management setup >>

IN THIS ARTICLE