Illustrated guide to tracing Imports and Exports

5 minute read time.

NOTE: This article is no longer relevant from 2021 R3 (Version 12 Patch 27) as the Engine Tracing functionality changed significantly in this version. See the PDFs attached to KB article "How to run an Engine trace in Sage X3?" for more details on both the pre-V12P27 and V12P27+ methods of setting up Engine Tracing.

You are running an Export or an Import, but it is not behaving as you expect.  How can you turn on Engine Tracing and/or Timing trace to investigate further?


The first thing to say is that you can activate a Timing Trace or Engine Trace through the normal mechanisms when running an Export or Import interactively (See "Related Articles" below for pointers how to do this).  The main issue with this is that it is not always easy to enable in a safe way on a live system.  More importantly, if you are running the Export/Import through the batch server, there is no way to enable these traces, other than by the method described in this article.

This method is relatively easy, although it does involve using some custom code.   Luckily, I will be providing a custom code example which we will use for this discussion.

The same principles apply equally for both Import and Export, but I will only be walking you through an example using an Export template.

NOTE: these notes have been created and tested with Sage X3 Version 12 Patch 24, although would expect these steps to also work with earlier versions of V12 and also V11

In summary we need to:
1.    Create and compile some custom code
2.    Add the custom code to the Import/Export template
3.    Run the Export or Import to create the trace files
4.    Disable the tracing

Steps in detail

1.    Create and compile some custom code

I have attached a file "SPEEXPTRACE.src" to this article (see link at bottom of this document), which you can use as an example of the custom code needed.  You may wish to modify this code to satisfy your own requirements.

a.    Copy the "SPEEXPTRACE.src" file to the "..\Folders\<FOLDERNAME>\TRT" directory where <FOLDERNAME> is the folder you wish to execute the tracing against.  In my example I am using SEED folder, so will copy the source code file to my "E:\Sage\X3ERPV12\Folders\SEED\TRT" directory.

b.    Login to X3 and connect to the relevant endpoint.  Then navigate to Development> Script dictionary> Scripts> Script Editor

Query back the "SPEEXPTRACE" file name and make any changes if needed.  The sample code sets up both Engine Trace AND Timing trace, although you may not need or want both.  

  • If you do NOT want Engine Trace, comment out lines 45, 52, 54 and 55
  • If you do NOT want Timing Trace, comment out lines 46 and 53

Also note that line 45 defines the Engine Trace mode as 15. The modes are described in the online help at https://online-help.sageerpx3.com/erp/12/staticpost/openlog/

Once you are ready to compile the source code, click the "Compile" button.

 

2.    Add the custom code to the Import/Export template

Navigate to Parameters> Usage> Imports/Exports> Import/Export template.  Query back the Export or Import template you wish to add tracing to.    Add "SPEEXPTRACE" as a "Specific script" to the template.

In this example, I will use the "SOH" template which is configured for Exports.

 

Save the change.

3.    Run the Export or Import to create the trace files

I will first run an Export interactively, and check it works as expected, then run the Export task through the batch server

a.     Run Export interactively

Navigate to Usage> Imports / Exports> Export

Query back the SOH template and fill in the parameters as you need.  Then click "OK" to run the export.

 

I see the results in the generated log file
 

If I check the "E:\Sage\X3ERPV12\Folders\SEED\tmp" directory, I can see there are two engine trace files (one from the adonix process and one from the corresponding sadoss process, as I asked for Level 15 engine trace to be created)
 

In the "E:\Sage\X3ERPV12\Folders\SEED\TRA" directory I see three files relating to my export, "F37571.tra" is the export job trace file we already saw interactively, "ADMIN_110148_210414141027.tra" is the raw timing trace file, and "F37573.tra" is the processed timing trace file
 




b.    Run Export through the batch server

Navigate to Usage> Batch server> Query submission

Enter the appropriate options for the "Export" task code


 
Click "Validation"

Enter the same parameters as we used for the interactive run


 
Click "OK" to submit the job to the batch server

Navigate to Usage> Batch server> Query management and wait until your job has been completed.
 


When I check the "E:\Sage\X3ERPV12\Folders\SEED\tmp" directory, I can see there are two engine trace files again from my batch job.

In the "E:\Sage\X3ERPV12\Folders\SEED\TRA" directory I will only see two files relating to my Export this time, the raw timing trace file and the processed timing trace file.

The batch server log file will be in the Batch Server TRA directory, in my case this is "D:\Sage\X3ERPV12\Folders\X3\SRV\TRA\RQT00064205.tra"

These note describes running the Export through the batch server as a one-time request, but it could also be submitted as a Recurring Task if required.  If you have added tracing to a Import/Export template that is already running as a recurring task, the tracing will begin for the next scheduled run.

4.  Disable the tracing

Once you have got the tracing you need, disable the custom code

a.  Navigate to Parameters> Usage> Imports/Exports> Import/Export template.  Query back the Export or import template you added tracing to.    Remove the "SPEEXPTRACE" from "Specific script" field in the template and save the change

b.  If you are running the import or export as a Recurring Task, the tracing will stop immediately.

Conclusion

Whilst it is possible to setup both timing trace and engine tracing for Export and Imports through the batch server, it requires some additional steps when compared to the configuring these options interactively.    These steps also allow you to more easily create the trace files for interactive users also.

Hopefully this article has helped you to understand the required steps.

Related Articles

If you review "Index page: Sage X3 Technical Support Tips and Tricks (March 2021)" you will see an article "Introduction to tracing classic functions" you may find the article itself interesting, but in particular it has a large section "Appendix2: Further Reading" which you may find useful

Illustrated guide to tracing Web Services https://www.sagecity.com/gb/sage-x3-uk/b/sage-x3-uk-support-insights/posts/illustrated-guide-to-tracing-web-services

Attachment

SPEEXPTRACE_v1.0.src.zip