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. Trace categories 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.

Both Trace categories and Trace destinations are called Trace parameters and they 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
    • POSTING
    • POSTING_PRINT
    • PRINTMGMT
    • DRADocument
    • ALERTS

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 TracingToDatabase 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 TracingToInfolog 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.

 

Note that you can match the records for the SSRS and DOCENTRIC category 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 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.

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 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.

IN THIS ARTICLE