Use asynchronous APIs in JavaScript code

This section describes how to use asynchronous APIs in JavaScipt code, and how to replace synchronous APIs with asynchronous APIs or Generic API Action steps if you have used them in your TruClient script.

In this topic:

Use asynchronous APIs

Available in version: TruClient 2020 SP1 and later

All asynchronous APIs except for TCA.done, TCA.doneWithError, and TCA.useAsyncAPI return a Promise object. The Promise object represents the eventual completion (or failure) of an asynchronous operation, and its resulting value. For more about promises, see the MDN documentation.

For example, to get a parameter value:

TCA.getParam("homePage").then(function(homepage){
  TCA.log(“home page is ” + homepage);
})

When all steps are complete, TCA.done() on success, or TCA.doneWithError() on failure must be called. Otherwise the step fails with an “Evaluate JavaScript code timeout” error. The above codes should change to:

TCA.getParam("homePage").then(function(homepage){
  TCA.log(“home page is ” + homepage);
  TCA.done(homepage);
}).catch(function (error) {
  TCA.doneWithError(error);
});

When using asynchronous APIs in places where a return value from evaluating JavaScript is needed, for example, in step argument fields, the return value must be returned by calling TCA.done(result) with the return value as the result argument.

TCA.getParam("homePage").then( homepage=> {
  TCA.done(homepage);
}).catch(error =>{
  TCA.doneWithError(error);
});

For the list of available asynchronous API functions that can be used in step argument fields in TruClient scripts, see Asynchronous functions.

Back to top

Replace synchronous APIs with asynchronous APIs

Available in version: TruClient 2020 SP1 and later

All synchronous APIs, except for evalXPath, have a corresponding asynchronous API version.

You can use asynchronous APIs to replace corresponding synchronous APIs wherever you have used them in your TruClient script.

Example of synchronous API:

var file_to_read = "c:\\test.txt";
if (IO.isExist( file_to_read) ){
  var content = IO.read(file_to_read);
  TC.outputMessage(content);
}

After replacing with asynchronous APIs, the codes changes to:

var file_to_read = "c:\\test.txt";
IOA.isExist(file_to_read).then(function(exist){
    if(exist){
        IOA.read(file_to_read).then(function(content){
            TCA.outputMessage(content);
            TCA.done(content);
        });
    }else{TCA.done();}
}).catch(function(error){
    TCA.doneWithError(error);
})

For the list of available asynchronous API functions that can be used in step argument fields in TruClient scripts, see Asynchronous functions.

Back to top

Replace synchronous APIs with Generic API Action steps

You can add asynchronous Generic API Action steps, or use them to replace existing synchronous APIs in your TruClient script.

To use Generic API Action steps:

1. Click Step in the toolbar, select Functions and drag a Generic API Action step to the location in the script where you want to use the parameter or attribute.

   

2. In the Step section, select the Category Name and Method Name for the API you want to add.

   Example: Select the TC category and getParam method.

   

3. In the Arguments section, type the name of the parameter you want to get, and the name of the JavaScript variable you want to be created.

   Example: After the variable is created (in this example, myParamVar), you can use it anywhere in the JavaScript code within TruClient.

   

To replace synchronous APIs with asynchronous Generic APIs that you created above:

1. In the menu toolbar, click and select Search.

2. Type the name of the synchronous API in the search box. TruClient highlights all entities in which the search string is found.

   Example: This section will use TC.getParam as an example. Type TC.getParam("myParam") in the search box.

   

3. Open the Arguments Editor and replace the synchronous API call used in the JavaScript code with the asynchronous Generic API you created.

   Example: Replace TC.getParam("myParam") with the new variable (in this case myParamVar).

   

   After the replacement, the previous code will look like this:

   

4. Repeat for all synchronous API calls that are used in the JavaScript code.

Back to top

See also:

• TruClient step arguments