Platform | 4. Procedure Execution in Progress Programs in Datasul

4.1. Objective

Enable - through scripts in Fluig - the execution of procedures (business rules) in Progress programs (BO – Business Object) in Datasul. The calls can be made to any procedure in a non-persistent way, available on programs in AppServer Progress in Datasul. The send and return parameters for each procedure will be respected, without the need to modify them. Access to procedures is available through a Webservices in Datasul called ExecBO. Figure 3.1.a below shows the overall architecture of the solution.

Figure 3.1.a

Figure 3.1. b presents the interaction among modules.

Figure 3.1.b

4.2. Programming Guide

WebServices ExecBO has the following methods:

The user's password in Datasul should be informed in a Base64-encoded way. For example, if the password is 'framework', its coding results in the string ' ZnJhbWV3b3Jr = '. There are several ways to perform this codification. In Javascript, we can use the functionbtoa(), according to the following example:

var pwd64 = btoa("framework");

The parameter jsonParams from the methods callProcedure or callProcedureWithToken shall contain the procedure parameters in JSON format. In this way, the string jsonParams should represent an Array of objects, where each object contains the following attributes:

• name: parameter name, matching the Progress procedure.

• type: parameter type, which may be: "input", "output" or "input-output".

• dataType: data type, which may be: "character", "integer", "decimal", "logical", "date", "datetime" or "temp-table".

• value: parameter value.
  
  

Assume a program named Test. p with a procedure named sum. This procedure receives two integer values as input parameters, it sums them and returns an integer as output. The call for the callProcedure in Java would be as follows:

String result = endpoint.callProcedure(“Teste.p”, “soma”, params);

Where params could have the following value:

[{"dataType":"integer","name":"value1","value":55,"type":"input"},

 {"dataType":"integer","name":"value2","value":99,"type":"input"},

 {"dataType":"integer","name":"result","value":0,"type":"output"}]

The method return is also an ABLTO list. In this example, the value of the result variable would be:

[{"dataType":"integer","name":"result","value":154,"type":"output"}]

Now let's see an example of calling a procedure that receives a temp-table as a parameter and returns it populated.

String result = endpoint.callProcedure(“Teste.p”, “getPaises”, params);

Where params has the JSON string with the declaration of the following TEMP-TABLE:

DEFINE TEMP-TABLE ttPais
   FIELD code AS CHARACTER LABEL Code
   FIELD name AS CHARACTER LABEL Name.

JSON String at TEMP-TABLE ttPais:

[{"name":"ttPais",

  "type":"input-output",

  "dataType":"temptable",

  "value":{"name":"ttPais",

           "fields":[{"name":"codigo","label":"Codigo","type":"integer"},

                     {"name":"nome","label":"Nome","type":"character"}],

           "records":[]

          }

}]

The return can be the following JSON string:

[{"name":"ttPais",

  "type":"input-output",

  "dataType":"temptable",

  "value":{"name":"ttPais",

           "fields":[{"name":"codigo","label":"Codigo","type":"integer"},

                     {"name":"nome","label":"Nome","type":"character"}],

           "records":[{"codigo":55,"nome":"Brasil"},

                      {"codigo":1,"nome":"USA"},

                      {"codigo":33,"nome":"Italia"},

                      {"codigo":15,"nome":"Canada”}]

          }

}]

In order to obtain the WSDL for the service, use the following URL:

		http://server:port/wsexecbo/WebServiceExecBO?wsdl

Where server:port is Datasul’s server and port.

Example of a Call to the ExecBO Service through a Process in Fluig

Through Fluig Studio, register the service WSExecBO according to the steps below:

a. From the Fluig view, select the Preview Service tab and then Include Service as shown in figure 3.2 a.

Figure 3.2.a

b. Register the new service similar to figure 3.2. b.

Figure 3.2.b

c. Select the Service Query option to test communications with the WebServices ExecBO and list the available operations, as shown in figure 3.2.c.

Figure 3.2.c

d. Create a script for the event of a process that has the need for information from a BO in Datasul. An example for the event afterTaskSave of a process can be seen below.

function afterTaskSave(colleagueId,nextSequenceId,userList) {
   try {
      // Uses the ServiceManager to obtain a reference to the service.
      var serviceProvider = ServiceManager.getService('WSEXECBO');
      var serviceLocator = 
          serviceProvider.instantiate('com.totvs.framework.ws.execbo.service.WebServiceExecBO');
      var service = serviceLocator.getWebServiceExecBOPort();
           
      var params = new Array();
 
      // Prepares the procedure parameters to be called in Progress
      var param1 = new Object();
      param1.dataType = "integer";
      param1.name = "value1";
      param1.value = 55;
      param1.type = "input";
      params[0] = param1;
 
      var param2 = new Object();
      param2.dataType = "integer";
      param2.name = "value2";
      param2.value = 99;
      param2.type = "input";
      params[1] = param2;
 
      var param3 = new Object();
      param3.dataType = "integer";
      param3.name = "result";
      param3.type = "output";
      params[2] = param3;
 
      var jsonParams = JSON.stringify(params);
      log.info(">>> Procedure parameters:");
      log.info(jsonParams);
 
      // Logs in and receives an authentication token
      var token = service.userLogin("framework", "ZnJhbWV3b3Jr=");
 
      // Call the procedure by passing the parameters and the authentication token.
      var resp = service.callProcedureWithToken(token, "testeProcedure.p", "sum", jsonParams);
 
      // Converts the result to an object
      var respObj = JSON.parse(resp);
 
      // Displays the result in the log.
      log.info(respObj[0].value);

   } catch (error) {
      log.error(error.message);
   }
}