JavaScript API ReferencePermanent link for this heading

The Fabasoft app.telemetry JavaScript API was introduced in the Summer Release 2009 and allows you to instrument any JavaScript application with instrumentation points to see what's going on in complex web applications.

In order to use the JavaScript API in your web application, you only have to include the softwaretelemetry.js SDK file and use the predefined functions and constants.

Constants and Configuration (JavaScript)Permanent link for this heading

All of the constants mentioned below are defined in the JavaScript API file softwaretelemetry.js on the global object called “apm”.

Version (JavaScript)Permanent link for this heading

apm.version contains the version number of the used script.

Example: apm.version = “17.2.7”

Flags (JavaScript)Permanent link for this heading

Flags are used to specify the type of an event and are passed as argument to every event call.

Name

Value

Description

apm.FLAG_NONE

0

normal event

apm.FLAG_ENTER

1

indicates a starting point

apm.FLAG_LEAVE

2

indicates an ending point

apm.FLAG_WAIT

4

indicates a wait condition

apm.FLAG_WARNING

8

mark event as warning

apm.FLAG_ERROR

16

mark event as error

apm.FLAG_PROCESS_INFO

32

force writing SessionInfo just before the event

Log Level (JavaScript)Permanent link for this heading

An event will only be logged if the event-level is lower or equal to the value selected in the session or log-definition.

Name

Value

Description

apm.EVENT_LEVEL_LOG

0

for events that should always be included and for logging parameters for the request overview

apm.EVENT_LEVEL_NORMAL

50

for general events for normal recording sessions

apm.EVENT_LEVEL_DETAIL

60

for detail level events for detailed session analysis

apm.EVENT_LEVEL_DEBUG

70

event with debugging information - highest level of precision with huge data amount and performance impact

Predefined Events (JavaScript)Permanent link for this heading

The SDK already provides a set of predefined events used for general purpose. For a full listing of all available predefined events see the generic chapter “Predefined Events”.

All predefined events are declared and available as global constants on the base variable “apm”.

Error/Trace Events:

Use these standard events to mark error, warning or info conditions in your application:

  • EVENT_ERROR
  • EVENT_WARNING
  • EVENT_INFO
  • EVENT_TRACE

Environment Configuration (JavaScript)Permanent link for this heading

Some global settings for the JavaScript SDK are configured globally on the environment object “apm.env”:

Name

Default Value

Description

apm.env.url

“web.telemetry”

The address to which the JavaScript API posts its data.

Important: this URL cannot point to a different domain or host as browser security prohibits this!

You can of course map a virtual directory to a different server using a load-balancer or similar methods.

apm.env.active

true

With this Boolean value you can switch the JavaScript API on or off

apm.env.flushtimeout

5000

(= 5 sec)

Delay for first telemetry data cache flush.

You can read the currently used flushtimeout (in ms) here, but you need to use apm.SetTimeout to change the timeout

… see “Method SetTimeout (JavaScript)

apm.env.flushinterval

60000

(= 1 min)

Telemetry data cache flush interval (in ms).

You can read the currently used flushinterval (in ms) here, but you need to use apm.SetInterval to change the interval.

… see “Method SetInterval (JavaScript)

apm.env.eventsperflush

500

Number of telemetry events sent with each cache flush.

apm.env
.reregistermodulestimeout

30000

Resync module registration on changes after this timeout (ms).

apm.env.reregistertimeout

600000

(= 10 min)

Interval (in ms) when synching full registration information with agent/server.

apm.env.exceptioncallback

null

This callback is called (if set) when an exception occurred.

For details see “Exception Callback (JavaScript)

Exception Callback (JavaScript)Permanent link for this heading

This callback is called (if set) when an exception occurred.

There are a number of cases when this can occur:

  • Data could not be transmitted to the Fabasoft app.telemetry WebAPI service.
  • Some other error happened when trying to send data to the Fabasoft app.telemetry WebAPI service.
  • The user callback has thrown an exception.

Syntax

apm.env.exceptioncallback = function(exobj, msg);

Parameters:

  • exobj (object): the JavaScript exception object or null if not available.
  • msg (String): String with a textual description of the occurred error.

Return Value:

The return value is ignored.

Remarks:

If apm.env.exceptioncallback is not set (null), the error message and a back trace will be logged to the JavaScript (Firebug)-Console (if available).

Usage Example

apm.env.exceptioncallback = function(exobj, msg) {

    alert("Exception:\nObject: " + exobj + "\nMsg: " + msg);

}

Configuration Functions (JavaScript)Permanent link for this heading

Besides setting the basic configuration variables (like apm.env.url) you can modify some parameters for your needs with the following setup functions described in the next sub chapters.

Method SetTimeout (JavaScript)Permanent link for this heading

Call apm.SetTimeout to change the initial timeout (delay) after which new events are being sent to the Fabasoft app.telemetry WebAPI service.

Syntax

apm.setTimeout(timeout);

Parameters:

  • timeout: Timeout/delay in milliseconds after which new events are sent to the Fabasoft app.telemetry WebAPI service.

Return Value:

This function does not return any value.

Remarks:

You can read the currently used interval from apm.env.flushtimeout. Altering this value directly is not recommended.

Usage Example

// if you know that an action will take 2 seconds you might raise the
// timeout to ensure that all events are done and save some requests

// to the server.

apm.SetTimeout(3000);

Method SetInterval (JavaScript)Permanent link for this heading

Call apm.SetInterval to change the interval in which the JavaScript API talks to the Fabasoft app.telemetry WebAPI service.

Syntax

apm.setInterval(interval);

Parameters:

  • interval: Interval in milliseconds in which the Fabasoft app.telemetry WebAPI service is called to refresh registration and session information.

Return Value:

This function does not return any value.

Remarks:

  • You can read the currently used interval from apm.env.flushinterval. Altering this value directly has no effect.
  • Using a very small interval is a bad idea because some browsers limit the count of concurrent connections opened with XMLHttpRequest.

Usage Example

apm.SetInterval(3000);

Method Flush (JavaScript)Permanent link for this heading

Call apm.Flush to trigger immediately sending events to the Fabasoft app.telemetry WebAPI service.

Syntax

apm.Flush(sendAllEvents);

Parameters:

  • sendAllEvents: If true all available events are transmitted to the server asynchronously.
    If false a set of events will be transmitted in an asynchronous manner.

Return Value:

This function does not return any value.

Registration Functions (JavaScript)Permanent link for this heading

Method RegisterApplication (JavaScript)Permanent link for this heading

Call this function once to provide information about the context of the application.

Syntax

apm.RegisterApplication(appname, appid, apptiername, apptierid);

Parameters:

  • appname: The name of your application
  • appid: The Id of your application
  • apptier: The tier inside the application
  • apptierid: Id to distinguish multiple services of one application tier

Return Value:

This function does not return any value.

Remarks:

  • Your application must be registered before any events can be fired.
  • The communication with the Fabasoft app.telemetry WebAPI service is setup when fist calling apm.RegisterApplication.

Usage Example

apm.RegisterApplication("Software-Telemetry", "Demo", "Browser", "browser");

Method RegisterModule (JavaScript)Permanent link for this heading

Call this function to register modules inside your application.

Syntax

apm.RegisterModule(modulename);

Parameters:

  • modulename Desired name of your module.

Return Value:

  • This function returns an object which you need to fire and register events.

Remarks:

  • Different modules are shown as different bars during the analysis.
  • For generic instrumentation of XMLHttpRequests there already exists a predefined module which can be obtained by calling apm.GetXMLHTTPModule(). (see “XMLHttpRequest”)

Usage Example

var page = apm.RegisterModule("Page");

page.RegisterEvent(1, "ButtonClicked", "ArticleID");
page.RegisterEvent(2, "PageLoaded", "event");

var module2 = apm.RegisterModule("AJAX Status");
module2.RegisterEvent(3, "CheckServices", "");

module2.RegisterEvent(4, "ServiceStatus", "status");

var xhrMod = apm.GetXMLHTTPModule();

Method RegisterEvent (JavaScript)Permanent link for this heading

Call RegisterEvent on a registered module instance object to provide information about every eventid used for event tracing.

Syntax

<module-instance>.RegisterEvent(id, name, param);

Parameters:

  • eventid: This is the id of the event you want to register.
  • description: The description of the event.
  • parameterdescription: Name of event parameters. If more parameters are used in one event, separate the parameter names by semi-colon (;). For example: "name;count;size"

Return Value:

This function does not return any value.

Remarks:

If an event has more than one parameter you need to separate the parameterdescription with semicolons (;).

Usage Example

var module = apm.RegisterModule("AJAX Request");

module.RegisterEvent(4, "RequestResult", "status;status Text");

Method RegisterFilterValue (JavaScript)Permanent link for this heading

Call apm.RegisterFilterValue for each valid filter value.

Syntax

apm.RegisterFilterValue(value, description);

Parameters:

  • value: value is the raw filter value.
  • description: This is the description which is presented in the Client-User-Interface as filter.

Return Value:

This function does not return any value.

Usage Example

apm.RegisterFilterValue("Article ID", "Description for `Article ID` filter.");

Context Handling Functions (JavaScript)Permanent link for this heading

Method CreateContext (JavaScript)Permanent link for this heading

Call APMCreateContext to create a new Software-Telemetry context. If the filter value matches a currently started session filter, logging is started for the current execution flow. Make sure to call APMReleaseContext when exiting the context.

Syntax

apm.CreateContext(contextid, filter);

Parameters:

  • contextid: The current context or null. You may call CreateContext multiple times to provide additional filter parameters. To do this you have to provide the previously created context id as the contextid input parameter in subsequent calls to CreateContext so that the CreateContext can be associated with the same request. To start a new context pass null as the contextid to get a new contextid as a return value from the CreateContext function.
  • filter: This value is used to match a filter of a started Software-Telemetry session. You should register filter values used by calling RegisterFilterValue (see “Method RegisterFilterValue (JavaScript)”)

Return Value:

  • If the API is active this function returns a new context token, otherwise null will be returned.

Remarks:

Usage Example

var contextid = apm.CreateContext(null, "filter1");

// ... proceed with application logic and fire events

apm.ReleaseContext(contextid);

Method ReleaseContext (JavaScript)Permanent link for this heading

Call APMReleaseContext to finish logging this request. Make sure to call apm.ReleaseContext for every request created with apm.CreateContext.

Syntax

apm.ReleaseContext(contextid);

Parameters:

  • contextid: The current context obtained by the corresponding CreateContext call.

Return Value:

This function does not return any value.

Remarks:

Usage Example

var contextid = apm.CreateContext(null, "filter");
// fire events,...

apm.ReleaseContext(contextid);

Method GetContext (JavaScript)Permanent link for this heading

Call apm.GetContext to get a context handle, which can be passed to another thread or process. This context information is used by the analysis components to track the control flow through the distributed environment.

The acquired context handle has to be submitted (either by transmitting over the network or in another way) to the thread/process being called which associates the calling thread with itself by passing the context to the apm.AttachContext-method.

Syntax

apm.GetContext(contextid);

Parameters:

  • contextid: the current context (obtained by CreateContext).

Return Value:

  • If the API is active this function returns a new context-token, otherwise null will be returned.

Remarks:

Usage Example

var contextid = apm.CreateContext(null, "AJAX");
var contextToken = apm.GetContext(contextid);

// pass contextToken to another function or another host
//  (for example to the webserver
via an x-apm-telemetry-context HTTP header).

//another function can use the token to asynchronously do some work
//  (for example loading additional data with AJAX)

apm.ReleaseContext(contextid);

Method AttachContext (JavaScript)Permanent link for this heading

Call apm.AttachContext to restore the context acquired through apm.GetContext in another thread, process or execution flow.

Syntax

apm.AttachContext(contextid, token);

Parameters:

  • contextid: The current context or null. If you attach to a context within a previously created context using AttachContext, pass the existing contextid as an input parameter. To start a new context pass null as the contextid to get a new contextid as a return value from the AttachContext function.
  • token: The context token which you want to attach to. You get such a context token by calling apm.GetContext.

Return Value:

  • If the API is active this function returns a new context-id if the contextid parameter was null, otherwise contextid will be returned.

Remarks:

Usage Example

var contextid = apm.AttachContext(null, token);

//proceed with application logic and fire events

apm.ReleaseContext(contextid);

Method GetSyncMark (JavaScript)Permanent link for this heading

Call apm.GetSyncMark to get a synchronization handle that can be passed to another thread or process to synchronize control flow.

Syntax

apm.GetSyncMark(contextid);

Parameters:

  • contextid: This is the context for which you want to get a sync-mark.

Return Value:

  • The return value is a Base64-encoded string which represents the token, or null if the API is inactive.

Remarks:

Usage Example

var contextid = apm.CreateContext(null, "Test");

var token = apm.GetSyncMark(contextid);

Method SetSyncMark (JavaScript)Permanent link for this heading

Call apm.SetSyncMark to pass a synchronization handle you got from apm.GetSyncMark for synchronizing the sequence of events.

Syntax

apm.SetSyncMark(contextid, token);

Parameters:

  • contextid: This is the context for which you want to set a sync-mark.
  • token: The sync-mark token you got from GetSyncMark form another thread/process.

Return Value:

This function does not return any value.

Remarks:

Usage Example

// registration,...

var context = apm.CreateContext(null, "Test");

// set the sync-mark we got from the web service (if any)
var token = document.getElementById('apmcontext').value; //e.g.: passed in an hidden field

// or an use the response header of an AJAX call

token = xhr.getResponseHeader("x-apm-telemetry-syncmark");

if (token) {
    apm.SetSyncMark(context, token);

}

module.Event(context, g_idLoaded, apm.LEVEL_DETAIL, apm.FLAG_NONE, "page loaded");

//...

apm.ReleaseContext(context);

Event Functions (JavaScript)Permanent link for this heading

Method Event (JavaScript)Permanent link for this heading

Call Event to log events with any number of parameters.

Syntax

<module-instance>.Event(contextid, id, level, flags, [params...]);

Parameters:

  • contextid: This is the context in which the event happens and is to be logged.
  • id: id of the event being processed (should have been registered with RegisterEvent – see “Method RegisterEvent (JavaScript)”).
  • level: event detail level for filtering. For the list of available log levels see chapter “Log Level (JavaScript)”.
  • flags: flags to mark events with Enter-, Leave- and/or Wait-semantic. More than one flags can be added together with a plus (+). For the list of available flags see chapter “Flags (JavaScript)”.
  • params...: You can specify any number of parameters after the flags parameter. null parameters are also allowed - even if they are in between normal parameters (null parameters are replaced by empty string parameters if needed).
    Note: do not specify objects as parameters!

Return Value:

This function does not return any value.

Remarks:

Usage Example

var module = apm.RegisterModule("AJAX Request");

var context = apm.CreateContext(null, "filter1");

module.Event(context, 7, apm.LEVEL_DEBUG, apm.FLAG_NONE, "param1", null, "param3", 4);

apm.ReleaseContext(context);

Method SendXMLHttpRequest (JavaScript)Permanent link for this heading

Call apm.SendXMLHttpRequest to do a fully instrumented XMLHttpRequest including passing x-apm-telemetry-context headers to the webserver and handling x-apm-telemetry-syncmark response headers for End-2-End instrumentation.

Syntax

apm.SendXMLHttpRequest(request, async, value, callback, context);

Parameters:

  • request: The XMLHttpRequest object.
  • async: Set this to true if you want to do an asynchronous request.
  • value: This is the data sent with the request.
  • callback: This callback is executed on every readystatechange (it does not apply for synchronous requests).
  • context: This is your current context in which the request is being sent.

Return Value:

This function does not return any value.

Usage Example

apmCheckServices = function() {
    var request = new XMLHttpRequest();
    var context = apm.CreateContext(null, "AJAX Request");

    var token = apm.GetContext(context);

    module.Event(context, 3, apm.LEVEL_NORMAL, apm.FLAG_ENTER);

    request.open("GET", "./AJAXHandler.ashx", true);

    apm.SendXMLHttpRequest(request, true, null, function(xmlhttp, context) {
        if (xmlhttp.readyState == 4) {
            try {
                var json_obj =
JSON.parse(xmlhttp.responseText);
                module.Event(context, 4, apm.LEVEL_NORMAL, apm.FLAG_NONE, "stockService: " + json_obj.stock);

                updateStatus('stockService', json_obj.stock);

                module.Event(context, 4, apm.LEVEL_NORMAL, apm.FLAG_NONE, "repositoryService: " + json_obj.repository);

                updateStatus('repositoryService', json_obj.repository);

            } catch (e) {

                module.Event(context, 4, apm.LEVEL_NORMAL, apm.FLAG_NONE,  "Exeption(" + e.name + "): " + e.description);

            }

        }

    }, context);
    module.Event(context, 3, apm.LEVEL_NORMAL, apm.FLAG_LEAVE);
    apm.ReleaseContext(context);
}

Fabasoft app.telemetry Button (JavaScript)Permanent link for this heading

Method Report (JavaScript)Permanent link for this heading

Call apm.Report to create a new feedback report.

The filter value will be matched to the description using the registered filter values. Use the textual description of the feedback entered by the user or generated by the application to identify the report session later again.

Syntax

apm.Report(contextid, filter, reportkey, description);

Parameters:

  • contextid: This is the context in which the report is generated.
  • filter: The raw filter value.
  • reportkey: A key value must be generated by the calling application and can be used to associate further descriptions to a feedback.
  • description: Application generated or entered by the user. The maximum length of the description is 32768 Bytes. (Prior to Fabasoft app.telemetry 2010 Fall Release (5.3) this parameter was limited to 256 Bytes.)

Return Value:

This function does not return any value.

Usage Example

var module = apm.RegisterModule("User Reaction");
var context = apm.CreateContext(null, "filter1");

module.Event(context, 7, apm.LEVEL_DEBUG, apm.FLAG_ENTER+apm.FLAG_WAIT);

alert("Press Ok to continue");

module.Event(context, 7, apm.LEVEL_DEBUG, apm.FLAG_LEAVE+apm.FLAG_WAIT);

var repkey = "myreport_" + Math.random();
apm.Report(context, "filter1", repkey, "Application has been waiting for user input");
apm.ReportValue(context, repkey, "username", "John Doe");
apm.ReleaseContext(context);

Method ReportValue (JavaScript)Permanent link for this heading

Call apm.ReportValue to add a key/value pair to an existing report.

Syntax

apm.ReportValue(contextid, reportkey, key, value);

Parameters:

  • contextid: This is the context in which the report is generated.
  • reportkey: match the reportkey of the Report function to associate the value with the report session.
  • key: A key describes the meaning of the value. Only one value can be associated to a key in one report session.
  • value: Textual value (max. 32 kBytes).

Return Value:

This function does not return any value.

Usage Example

SeeMethod Report (JavaScript)

Method ReportContent (JavaScript)Permanent link for this heading

Call apm.ReportContent to add content to an existing report.

Syntax

apm.ReportContent(reportkey, filename, value, encoding, mimetype);

Parameters:

  • reportkey: match the reportkey of the Report function to associate the content with the report session.
  • filename: A filename describing the content of the file. (max. 256 Bytes) – this is the name of the file in the reported session with which the data is persisted.
  • value: This is the content – a string or byte-array to attach to the report.
  • encoding (optional): The encoding type of the value content. Supported encoding types are:
    • "plaintext" (=default: if missing or null): string value will be written directly into the target file.
    • "base64": the passed content value must be Base64-encoded and will be decoded as Base64-value on the server for writing into the target file. This encoding allows you to attach binary data, images or similar to the report session.
  • mimeType (optional): The MIME-type helps to identify the uploaded file content. You can provide any valid mime type string:
    • "text/plain" (=default: if missing or null)
    • "image/png"
    • "application/octet-stream"
    • etc.

Return Value:

This function does not return any value.

Usage Example

var module = apm.RegisterModule("User Reaction");
var context = apm.CreateContext(null, "filter1");

module.Event(context, 7, apm.LEVEL_DEBUG, apm.FLAG_ENTER+apm.FLAG_WAIT);
alert("Press Ok to continue");
module.Event(context, 7, apm.LEVEL_DEBUG, apm.FLAG_LEAVE+apm.FLAG_WAIT);

var reportkey = apm.utils.Encode64(apm.utils.CreateContextToken());

apm.Report(context, "filter1", reportkey, "Application has been waiting for user input");
apm.ReportValue(context, reportkey, "username", "John Doe");
apm.ReportContent(reportkey, "page.html", document.documentElement.outerHTML);
apm.ReportContent(reportkey, "screenshot.png", base64encodedImageContent, "base64", "image/png");
apm.ReleaseContext(context);

Remarks:

To allow applications to post random content, Fabasoft app.telemetry WebAPI supports posting content directly to the Fabasoft app.telemetry Web-API. Provide the reportkey and the filename as URL-parameters after the "?ReportContent" tag and the send the value as POST-data content.

Usage Example – ReportContent POST

var request = new XMLHttpRequest();
var url = apm.env.url + "?ReportContent";
url += "&reportkey=" +
encodeURIComponent(reportkey);
url += "&filename=" +
encodeURIComponent(filename);
request.open("POST", url, true);
request.send(
value);

Method ReportDialog (JavaScript)Permanent link for this heading

The JavaScript API provides a full-featured implementation of a report dialog to ask the user for feedback which is sent with the other report data. When used with modern web browsers also a web-based HTML5 browser screenshot is available.

Syntax and UsagePermanent link for this heading

Call apm.ReportDialog to show the end user a feedback dialog which will invoke the apm.Report call with the description entered by the user and if defined it will append additional metadata information and files to the same report session.

Syntax

apm.ReportDialog(contextid, filter, reportkey, description, parentNode, metadata, formOptions);

Parameters:

  • contextid (optional): This is the context in which the report dialog is opened by the user (e.g. context of user button click). If you do not have an active context pass "null" and the API will create the required context internally. This context is released after the dialog is created and displayed!
  • filter (required): The raw filter value.
  • reportkey (required): A key value (string) must be generated by the calling application to associate further descriptions to a feedback (as unique value for every generated report). The key value can be used to attach further metadata/attachments.
  • description (optional): Optionally a predefined description string may be passed to this function to provide a start-up text for the description input text field presented to the user within the feedback dialog – the user can change this text. If empty ("") the user will see an empty input text field in the dialog where he can input his own feedback text.
  • parentNode (optional): This is the parent DOM-Node to which the created dialog is added, if you do not specify this parameter it defaults to window.document.getElementsByTagName('BODY')[0].
  • metadata (optional): The metadata object is an optional parameter to define additional metadata to display in the report dialog and attach to report session. The metadata object has the following format:

_metadata object Syntax/Example

function previewCallback(filename, fileObj) {
  // open preview window
}
function getContentCallback(filename, fileObj) {
  // return base64-encoded file content as string
}
var metadata = {
fields: [    // custom editable fields (with label and input-control)
               //
shown above feedback textbox
    {
      type: "text",             // = default
      name: "email",            // field name
      label: "E-Mail Address",  // field label (optional)
                                //
... if not set, name is used as label
      value: "test.user@mydomain.com",    // preset value
                                //
(initially filled into the text box)
      validate: function(name, value) {   // validate function
        //
that must return true on OK
        //
or a text that is displayed otherwise (if invalid)
        if (value && value.length > 10) {
             return true;
           } else {
             return "Value is invalid - shorter than 10 chars!";
           }
      },
      html5type: "email",    // optional set the html5 input type
                             //  
(for better handling on tablets)
      layout: "two-column"   // optional (default if not defined
                             //  
is one-column with 2 rows)
    },
    {
      type: "checkbox",
      label: "My Checkbox",
      
name: "check1",
      checked: true          // preselection
    },
    {
      type: "select",         // combo box
      label: "My Combo", name: "combo1",
      options: {
        "val_1": "Value 1",
        "val_2": "Value 2",
        "val_3": "Value 3"
      },
      value: "val_2"         // preselection
    },
    {
      type: "rating",      
// radio-button rating control
      label: "Recommend", name: "rate2",
      count: 5,             // number of radio buttons for rating
      leftHint: "bad",
      
rightHint: "good",  // optional hint text above radio buttons
      radioLabels: ["--","-","o","+","++"],  // radio button labels
                     //
(below) can be customized (default: 0..count-1)
      value: 2,             // initial selection
      layout: "two-column"  // if not two-column, then a single-column
                            //  
layout with 2 rows is used
    },
    {
      
type: "property",
      
label: "Readonly Property",
      
name: "property1",
      
value: "value_1"
    
},
    { type: "hr" }   // Horizontal Line
  ],
  files: [    // custom files/contents to be uploaded with session
    {
      filename: "my-screenshot1.jpg",
      checked: true,   // default state of checkbox
      name: "screenshot",  // internal key to set id for checkbox HTML-
        //
tag ("apm-chk-file-" + id) ... valid chars: [-A-Za-z0-9_]
      label: "Include Screenshot",  // label for list entry
      previewLabel: "Preview...",   // label for preview button
                                    //
(if “” -> no preview button/link)
      previewCallback: previewCallback,  // callback to view file content
                                         //  
(if null -> no button)
      getContent: getContentCallback,    // callback to get file content (base64-encoded)
      mimeType: "image/jpeg"// mime-type of file content
    },
    {
      filename: "my-system-information.txt",
      checked: true,
      name: "softwareinfo",
      label: "Include Software Repository/Registry",
      previewLabel: "Preview...",
      previewCallback: previewCallback,
      getContent: getContentCallback,
      mimeType: "text/plain"
    },
  ],
  infos: [        // list of key-value pairs for additional text information
    {
      name: "user",        // name of attribute (sent to server)
      label: "Username",   // optional: display string for GUI
                           //  
(if not set the name is displayed)
      value: "Test User"   // value of attribute (sent to server)
    },
    {name: "E-Mail", value: "test.user@mydomain.com"},
    {name: "version", label: "Client-Version", value: "1.2.3.4"}
  ]
};
apm.ReportDialog(null, filter, reportkey, description, parentNode, metadata);

  • formOptions (optional): Since version 2013 Fall Release this optional parameter can be used to pass additional parameters.
    • formid: to load a designed on-premise form via the WebAPI. This will prevent the default SDK dialog from being shown and will instead load the form with the given ID. Format: formOptions = { formid: "<FORMnnnnn>" }
    • language: to load a specific language translation of a designed on-premise form. If not defined the language of the HTML-page where the dialog is embedded will be used (document.documentElement.lang). If no form translation for the desired language can be found the default dialog without text translations will be loaded. Format: formOptions = { language: "<xy>" }

_formOptions object Syntax/Example

var formOptions = {
  
  formid: "FORM12345",
    language:
"de",
};
apm.ReportDialog(null, filter, reportkey, description, parentNode, metadata, formOptions);

Return Value:

This function does not return any value.

Remarks:

  • Calling this dialog when the API is disconnected results in an alert with the message stored in apm.env.report.reportingunavailable, you can call apm.IsConnected() to check if this will happen.
  • During the lifetime of the dialog all iframe, object, and embed tags are set to visibility: hidden, after closing the dialog all changed elements are set back to their original visibility value.

Customizing Report DialogPermanent link for this heading

The application developer can customize the texts used in the dialog and optionally can define the path where the image file resources are located.

To customize the dialog settings just overwrite the default values in the apm.env.report API variables:

Name (apm.env.report. ...)

Default Value

Description

dialogtitle

“Application Feedback”

Title displayed at the top of the dialog (heading)

dialogpoweredby

“powered by”

Powered by… text above logo

poweredByLogo

<empty>

optionally set a custom poweredBy logo – keep empty to use the default app.telemetry logo (will be set as img-src attribute)

poweredByLogoLink

<empty>

optionally define a custom link target for the powered-by logo (set as a-href attribute) – keep empty to use the default URL (http://www.apptelemetry.com)

hidePoweredBy

false

could be set to true to fully hide the powered-by logo and text

hideBackgroundImage

false

could be set to true to hide the background image tree to save some space on the left

enableLogoLinkToHomepage

true

if true the Logo represents a hyperlink to www.apptelemetry.com otherwise there will be no link but only the logo

dialogtext

“Let us know your feedback:”

Default label text for main feedback input box (shown above textarea).

dialogtextminlength

0

Minimum number of characters the user has to enter to be able to submit the feedback (if not fulfilled the dialogtexttooshort-text is displayed).

dialogtextmaxlength

1000

Maximum number of characters the user can enter in the text-field (textarea limited with maxlength-property) - if set to 0 the length is not limited (maxlength-property not set)

dialogtexttooshort

“The feedback you entered is too short.”

Displayed error text when user tried to send the feedback but did not enter enough text (characters) into the textarea.

dialogsubmittext

“Send”

Label text for send/submit button.

dialogcanceltooltip

“Cancel”

Label text for cancel/close button.

closeonescape

true

If true the dialog will be closed (cancelled) on pressing the escape key.

reportingunavailable

“The feedback functionality is currently unavailable.”

Text shown when feedback functionality is not available (base URL not configured correctly or webAPI not reachable).

imagepath (ignored)

null

The imagepath parameter is not used any longer.
Images (referenced from apmdialog.css) are loaded directly from the WebAPI

scripting

true

This setting allows you to disable any scripting field functions possibly used in additional form fields.

Additional Customization Variables (for providing metadata content):

In order to use the automatic screenshot/softwareinfo integration of the Fabasoft web browser plugin the following conditions must be fulfilled:

  • Fabasoft web browser plugin is installed on every client machine using the feedback dialog
  • The JavaScript part of this Fabasoft plugin (fscplugin.js) is included and loaded before the softwaretelemetry.js.
  • Your server location is trusted for Fabasoft plugin usage in the registry of every client using the feedback dialog: HKEY_CURRENT_USER\Software\Fabasoft\WebClient\TrustedSites … with a „String“-key containing the application server URL as name and the value “1” as value. (E.g.: http://server.mydomain.com = 1)

Otherwise you can provide your own file attachments within the metadata files list including the callback functions for getting the content and previewing the file.

  • apm.env.report.screenshot =
    {enabled: true, label: 'Include Screenshot', previewlabel: 'Preview...'}
    ... to customize the Plugin-based screenshot content attachment
  • apm.env.report.softwareinfo =
    {enabled: true, label: 'Include Software Repository/Registry', previewlabel: 'Preview...'}
    ... to customize the Plugin-based screenshot content attachment
  • apm.env.report.displaymetadata = true; ... set this option to false to hide additional info key-value pairs attached to the report session (information is only hidden but sent with report)
  • apm.env.report.metadatatitle = 'Your feedback will include the following information:' ... section title label for additional info key-value pairs
  • apm.env.report.filestitle = 'You can attach the following files to your feedback:' ... section title label for additional attached files (and screenshot/softwareinfo attachments)

Available event callbacks: (default they are not defined - null)

  • apm.env.report.onopen = function() { ... }
    • The onopen-callback is invoked after the dialog has been created and inserted into the DOM, but before the iframe, object and embed elements are hidden.
  • apm.env.report.oncancel = function(data) { ... }
    • The oncancel-callback is invoked when the user cancels the feedback dialog with the close/cancel button.
    • If the assigned callback function returns false the dialog will not be canceled/closed. In normal cases the function should return true.
    • The data argument passed to the oncancel callback is the apm.env.report.data variable which can be read - but should not be changed here - changes made to the description property will be overwritten when the user presses OK(in case the oncancel-callback returns false and the user presses OK afterwards).
  • apm.env.report.onsubmit = function(data) { ... }
    • The onsubmit-callback is invoked when the user presses the submit/OK button in the feedback dialog.
    • If the assigned callback function returns false the dialog will not be submitted (no report sent) and will stay open. In normal cases the function should return true. You can use this callback to validate the input and inform the user about what he missed to enter (min text-length, E-Mail address, whatever)
    • The data argument passed to the onsubmit callback is the apm.env.report.data variable which can be read and also modified, changes to the description property are not reflected in the input element the user sees and are overwritten the next time the user presses submit (if you returned false to keep the dialog open before).
  • apm.env.report.onclose = function() { ... }
    • the onclose-callback is invoked after the dialog has been removed from the DOM, the iframe, object and embed elements are already set to their original visibility values.
  • The apm.env.report.data object:

Data Structure (apm.env.report.data)

apm.env.report.data = { contextid, filter, key, description, }

  • The contextid, filter and key values have already been assigned with the arguments passed by the initial call of apm.ReportDialog(...)
  • The description field contains the value the user entered in the text input field inside the dialog
  • e.g: the developer can use the oncancel/onsubmit-callback to get the value the user entered in the feedback dialog and use it in his own application logic.

Special parameter access:

  • env.report.dialognode: this variable stores the DOM-node (DIV) used to display the feedback dialog.

Internal methods to control the dialog (should only be used in exceptional cases):

  • apm.utils.createReportDialog() ... create and show dialog (is called by ReportDialog main function)
  • apm.utils.cancelReportDialog() ... same as user cancels dialog (Close/X)
  • apm.utils.removeReportDialog() ... remove dialog DIV (is called by cancelReportDialog and submitReportDialog)
  • apm.utils.submitReportDialog() ... same as user presses submit/OK

Customizing Report Dialog Screenshot/PreviewPermanent link for this heading

Since Winter Release 2012 the app.telemetry feedback dialog supports an HTML5 screenshot to be taken and submitted via the feedback dialog without any browser plugin/addon. This feature is supported in all modern web browsers which support the HTML5-canvas element native.

To customize if the HTML5 screenshot should be enabled for your website and to customize the display texts used for the HTML5 screenshot attachment inside the feedback dialog use the following properties of the apm.env.report data object:

Name (apm.env.report. ...)

Default Value

Description

enableHTML5Screenshot

true

Enable (true) / disable (false) support and automatic rendering of HTML5 screenshot on opening the feedback dialog

HTML5ScreenshotPreview

“Preview”

display label for preview screenshot link

HTML5ScreenshotLoading

“loading...”

display label for preview screenshot link during loading/rendering of screenshot

HTML5ScreenshotLabel

“Web Browser Screenshot”

display label for HTML5 screenshot file attachment listing

HTML5ScreenshotPreviewUnavailable

“N/A”

display label for preview screenshot link if no screenshot is available or loading/rendering failed

HTML5ScreenshotClosePreviewTitle

“Close”

Button label for close button for preview window.

HTML5ScreenshotLoadingTimeout

30000

timeout (in msec) after which the loading/rendering of the HTML5 screenshot will be cancelled

Since version 2013 Summer Release the screenshot preview was redesigned and improved supporting the following new features:

  • Crop/cut screenshot to desired size (especially to hide other application windows captured with the native Fabasoft plugin screenshot)
  • Mark screenshot: mark interesting/important parts in the screenshot with a colored (red) rectangle
  • Black out: hide parts you don’t want to transmit with your feedback from the screenshot by painting those areas with black filled rectangles

These new features …

  • require HTML5-support in the web browser (only modern browsers like Chrome, Firefox or IE9+ are supported)
  • work for captured HTML5-screenshots of any web page and for native Fabasoft plugin screenshots

In order to customize the label and button texts of the new screenshot preview dialog use the following configuration parameters of the apm.env.report data object:

Name (apm.env.report. ...)

Default Value

Description

screenshotPreviewTitle

“Preview”

Displayed top title for the screenshot preview dialog.

screenshotPreviewHelpText

“Select your desired screenshot part ...”

This is the help text displayed in the preview dialog to explain the crop/mark features and give the user other hints for using this preview dialog.

screenshotPreviewCropButtonLabel

Crop

Button label for the “cut/crop” feature.

screenshotPreviewMarkButtonLabel

“Mark”

Button label for the “mark” feature.

screenshotPreviewBlackoutButtonLabel

“Black out”

Button label for the “black out” feature.

screenshotPreviewCancelButtonLabel

“Cancel”

Button label for the “cancel/close” preview dialog.

screenshotPreviewOkButtonLabel

“OK”

Button label for the “ok/apply” to accept modifications and close preview dialog.

Using Report Dialog ExamplePermanent link for this heading

Usage Example

...
  <script type="text/javascript" src="softwaretelemetry.js"></script>
  <script language="javascript">
    function sendFeedbackFunction() {
      apm.env.report.dialogtitle = "Report Your Problems";
      apm.env.report.oncancel = function() {
        console.log("oncancel callback called");
        return true;
      
};
      apm.env.report.onsubmit = function(data) {
        console.log("onsubmit callback called");
        console.log(["user sends feedback: ", data]);
        return true;
      
};
      var metadata = {
        fields: [
          { name: "email", label: "E-Mail Address", value: "user@mydomain.com",
            validate: function(name, value) {
              if (value && value.length > 10) { return true; }
              else { return "Value invalid - shorter than 10 chars!"; }
             }
          }
        
],
        files: [
          {
            filename: "test-screenshot.png",
            checked: true,
            name: "screenshot",
            label: "Application Screenshot",
            previewLabel: "Preview...",
            previewCallback: previewCallback,
            getContent: getImageContentCallback,
            mimeType: "image/png"
          
},
          {
            filename: "test-system-information.txt",
            checked: false,
            name: "softwareinfo",
            label: "Application Software Info",
            previewLabel: "Long Preview Text...",
            previewCallback: previewCallback,
            getContent: getTextContentCallback,
            mimeType: "text/plain"
          
}
        ],
        infos: [
          {name: "Username", value: "Test User (domain\\user.name)"},
          {name: "e-Mail", value: "test.user@mydomain.com"},
          {name: "Client-Version", value: "1.2.3.4"},
        ]
      };
      apm.ReportDialog(null, "myfilter", "myReportKey",
          
"description passed via API call", null, metadata);
      return false;
    }
  </script>

  <!-- display a feedback button with the Fabasoft app.telemetry logo
        provided via stylesheet classes -->
  <a href="#" title="Feedback" onclick="sendFeedbackFunction();">
    <span class="apm-feedback-icon apm-ic-logo20"></span>
  
</a>

Status Functions (JavaScript)Permanent link for this heading

Method HasActiveContext (JavaScript)Permanent link for this heading

Call apm.HasActiveContext to test, if a software-telemetry session is active for some logging level. This information should be used to avoid costly operations preparing parameters for events that are currently not logged.

Syntax

apm.HasActiveContext(contextid, level);

Parameters:

  • contextid: This is the context for which you want to know if the event will be logged.
  • level: The event level of the event you prepare parameters for.

Return Value:

  • The return value is true if the event will be logged.

Usage Example

var context = apm.CreateContext(null, "filter value");
// application logic
if (apm.HasActiveContext(context, apm.LEVEL_DEBUG)) {
    // prepare parameters, set events,...

}

apm.ReleaseContext(context);

Method IsConnected (JavaScript)Permanent link for this heading

Call apm.IsConnected to test, if the application has successfully registered to a Fabasoft app.telemetry agent/WebAPI. Your application must not make any assumptions based on the return value of this function as there are many reasons that may lead to a false being returned from this function even though the communication with the WebAPI be possible in general.

Syntax

apm.IsConnected();

Parameters:

This function does not take any arguments.

Return Value:

  • This function returns true if the communication to the configured Web-API web service is successful.

Remarks:

  • A call to this function does not result in an XMLHTTPRequest to the web service; instead, it returns the result of past communications, depending on when you call this function you may need to trigger a flush before.
  • You can check if the API is active by checking apm.env.active. See “Environment Configuration (JavaScript)” for details.
  • Please note that versions prior to Fabasoft app.telemetry 2010 Fall Release (5.3) always returned false.

Usage Example

apm.RegisterApplication("Fabasoft app.telemetry", "", "Client", "");
apm.Flush(); // trigger a flush to make sure at least one request was done
// (much) later:

if (apm.IsConnected()) {
  
  console.log("APM Software-Telemetry connected");
}