This documents covers how to troubleshoot and handle exceptions in Cloud Application studio and explaining the basic scenarios like debug a background job, tracing, debug a script file.

Thanks to my colleagues Vaibhav Kwatra,Kartik Saini,bhupinder sharma as they have helped and contributed in preparation of this document.

Table of Contents

1. Troubleshooting

   

1.1. Debugging

        Below are the steps that will explain the basics for debugging a solution:-

1. Set a Breakpoint.
2. Delete a Breakpoint.
3. Disable or Enable a Breakpoint.
4. Start and Stop Debugging.

    Set a Breakpoint

• Open a script file.
• To set a breakpoint in the code editor go to the left grey margin of the code editor, click a line of executable code and press F9.
• As shown in below screenshot a red dot appears in the margin indicating breakpoint is set.

                           

Delete a Breakpoint

• Press F9 in the code line to delete a particular breakpoint.  The red dot is deleted.
• Go to Breakpoints tool window and click delete all or Ctrl +Shift+F9.

Disable or Enable a Breakpoint

• Click on disable all breakpoints to disable a particular breakpoint in Breakpoint tool window.
• Click enable or disable all breakpoints to disable all breakpoints in script file in Breakpoints tool window.
• Select the checkbox disabled Breakpoint for enabling a particular breakpoint in the Breakpoint tool window.
• Click Enable or disable all breakpoints to enable all disabled breakpoints, in the toolbar ->Breakpoints tool window

                                 

Start and Stop Debugging

To start with debugging, follow below steps to choose if we want to enable it for particular business user:

• Go to Administration-> options and settings -> debugging and tracing
• Check checkbox ‘Enable for business user’ option and enter name of particular user for whom we want to enable debugging otherwise it will be enabled for all the business users.
• Select appropriate option from the drop down which has to be performed before starting the debugging.
  • Never save, refresh and activate.
  • Prompt to save, refresh and activate.
  • Always save, refresh and activate.

Refer below screenshot:

                       

• To start debugging, inthe Debug toolbar, click or press F5.

The code editor is brought to the foreground and Debug windows are enabled, for example, the Breakpoints Window and the Locals window. The debugger is in run mode and you cannot edit your code anymore.

Find below description for each window:-

• Output window –It contains information of when debugging has been started by which business user and how many rows retrieved/affected by the code from database. If on retrieval result set is fetching 3 rows it would be showing us message in output window or if result is failing with null reference, then in output window we can easily find which row is returning null result and causing failure. If you are getting any exception in UI, or from results of a job, we can run debugger and check in output window, when it fails, definitely you will get the clue from the output window regarding the failure and can easily rectify and correct it in code.
• Call Stack Window –This window would be containing information related to which row is currently being executed by debugger.
• Locals Window –It contains information of all the variables which we have declared in our code, this window is very helpful as it tell us which variable contains what value, So that we could easily come to know if all the values are coming as expected.
• Breakpoints Window –It contains all the breakpoint information with line number and file name.

• To stop debugging, in Debug toolbar, click or press SHIFT + F5. We can make changes to our code once debugging has been stopped.

          Refer the below table for debugging shortcuts:

Activity	Key
Start Debugging	F5
Stop debugging	Shift+F5
Step through the code one statement at a time (Step over)	F10
You are inside a script file and want to return to the calling script file (Step out)	Shift+F11
Bypass the code without execution to next breakpoint	Shift +F11
Toggle breakpoint	F9
Delete all breakpoints	Ctrl+Shift+f9

1.2. Tracing

In scenarios, where we need to keep on track of our variables used in code, we trace such information by starting Tracing in studio.

• As a prerequisite we need to write trace statements.
• It contains message string and variable name, whose value need to be tracked.
• Below given 2 functions are used to capture information from code and write trace statements:-
  • Trace.Info (string, variables)
  • Trace.Error (string, Variables)

Below screenshot shows on starting tracing, when we perform operation from UI, it will go to action and trace statements, written in code.

To view traces, we can open trace explorer, trace explorer contains:

• Local Traces: It contains the list of all the traces that has been captured by the particular user.
• Incident Traces:It contain the incident that user reports in a productive system and this information can help you track down the source of the issue that the user is experiencing. Incident traces contain the same information as local traces, but remain accessible until the incident is closed.

                                   

2. Exception Handling

Exception handling plays important role in maintaining the normal flow of the application and to prevent the abnormal termination of the application.

Below are the keywords which are used to handle exception during the execution of an application:

• Messages

• Syntax:

message <message ID> text “<message text>” [: <data type 1>[, <data type

2>[, <data type 3>[, <data type 4>];

• Description:

Use the message keyword to define a message between two business objects. The definition of a message includes the message ID, the message text, and, optionally, data types of up to four message parameters.

• Example:
  • Message without parameters:

message DateMissing text “Due date of invoice is missing”;

• Message with two parameters:

message ReferenceInvalid text “Reference to sales order &1 invalid for &2″ : IntegerValue, ESF:AdressType;

Refer below screenshot for usage of messages:-

• Raises

• Syntax:

raise <message name>.Create (<severity> [, <message text variable>]*);

• Description:

You can use the raise keyword to raise messages that have been declared in the business object definition.

The Create method has one mandatory parameter: the severity. You have to supply the severity as a string:

• “E” for errors
• “W” for warnings
• “S” for success messages
• “I” for information

As additional optional parameters you can supply the values for placeholder variables as declared in the message text.

• Example:

import ABSL;

raise Information_Message.Create(“I”);

raise Error_Message.Create(“E”, “Error”);

raise Warning_Message.Create(“W”, “Warning”, 25);

raise Success_Message.Create(“S”, this.Test_Extension_Field);

3. Scenarios

3.1. Debugging

3.1.1.  Debug a background job

We have scheduled a background job to send email notification to those contacts whose opportunities are going to expire soon. 

• Open MDR solution in cloud studio, open .run file to check the action associated with MDR as show in below screenshot:

             

• Open the action ‘Create_MDR’ script file.
• Set breakpoints in action code which gets hit when job runs.
• Depending upon the error we can set break point either at starting of code (script file) or to a particular point.

                 

• Start debugging before performing action, debugging windows open up.

                     

• As shown in below screenshot, open OWL screen, which allows us to schedule jobs.

             

• Scheduling job as shown below, which will internally call our action code and hit breakpoints.

                   

• Code line getting executed currently will appear in yellow line.
• Press F10 to go to next line in our code or to jump directly to next breakpoint press shift+F11 as shown below.

   

             

• We could check value by hovering mouse over a particular variable.
• Local variable value can be checked in local window as well, as shown in below screenshot.

                       

• Job fails with below mentioned system exception :

         

                       

• The time job fails, we could find out in output window which code line is causing the issue or returning null result.

             

• We could go to particular code line & rectify.

3.1.2.  Debug a script file

• Set the breakpoints on the script files.

                   

• Open the required screen for debugging.

                       

• Fill the necessary fields and press enter.
• The local window will appear with values.

                           

                               

             

3.2. Tracing

• Open window to schedule job from studio, it will automatically open in Trace mode, as shown below, perform action.

                                 

• Once operation gets completed, open trace explorer and click on particular trace action file to check the logs.

                             

To capture error traces, we could use Trace. Error (string, variable) function, below are the screenshot with implementation:

• Similar to above example, starting tracing after adding Trace. Error statement with required error message.

                                 

• Performing operation from particular screen, on entering wrong data values it shows validation messages that we have implemented.

             

• On opening traces for the same operation we could stop the traces and open that local trace file.

            As shown below it captures traces of custom error messages.

                 

                   

3.3. Exception Handling

          Exception handling by creating custom errors to maintain the normal flow of the application and sending the error list to concerned troubleshooting team.

          In our case, an opportunity does not have associated primary contact as it was not getting handled in our code, hence system was throwing an unhandled ‘Null’ exception.

          Refer below screenshot for system exception:-

             

    To handle this scenario

    Follow below steps:

• Declare a message that will contain custom message, shown instead of system error.
• In action code place a raise statement which will be handling our exception.
• This custom message gets replaced with system exception in job logs.
• Capturing error messages and sending an email notification to concerned troubleshooting team.

    Screenshot for declaration of custom messages:

             

    Screenshot for using Raise statement and sending Email with custom error messages:

             

    Screenshot with handled exception: