Histórico da Página

<div id="main-content" class="wiki-content group">
	<h3
		id="id-4.ExecuçãodeProceduresemProgramasProgressnoDatasul-4.1.Objetivo">
		<strong>4.1. Objective</strong>
	</h3>
	<p align="LEFT">
		<span>Enable - through </span>script<span>s</span><span> in </span><strong>Fluig</strong><span>
			- the execution of procedure</span><span>s</span><span> (business
			rules) in Progress programs (BO – Business Object) in </span><strong>Datasul</strong><span>.
			Th</span><span>e </span><span>call</span><span>s</span><span> c</span><span>an</span><span>
			be mad</span><span>e</span><span> to any procedure in a
			non-persistent way, availabl</span><span>e</span><span> on programs
			in </span><strong>AppServer Progress</strong><span> in </span><strong>Datasul</strong><span>.
			The send and return parameters for each procedure will be respected,
			without the need to modify them. Access to procedures </span><span>is</span><span>
			available through a </span><strong>Webservices</strong><span> in </span><strong>Datasul</strong><span>
			called </span><strong>ExecBO</strong><span>. Figure </span><strong>3.1.a
		</strong>below<span> shows the overall architecture of the solution.</span>
	</p>
	<p align="LEFT">
		<span><img class="confluence-embedded-image image-center"
			src="http://tdn.totvs.com/download/attachments/81789185/screen1.png?version=1&modificationDate=1380888898000&api=v2"
			data-image-src="http://tdn.totvs.com/download/attachments/81789185/screen1.png?version=1&modificationDate=1380888898000&api=v2"></span>
	</p>
	<p align="LEFT" style="text-align: center;">
		<span><strong>Figure 3.1.a</strong><br /></span>
	</p>
	<p align="LEFT">
		<span>Figure 3.1. b presents the interaction among modules.</span>
	</p>
	<p align="LEFT" style="text-align: center;">
		<span><img class="confluence-embedded-image image-center"
			src="http://tdn.totvs.com/download/attachments/81789185/screen2.png?version=1&modificationDate=1380888982000&api=v2"
			data-image-src="http://tdn.totvs.com/download/attachments/81789185/screen2.png?version=1&modificationDate=1380888982000&api=v2"><strong>Figure
				3.1.b</strong></span>
	</p>
	<p align="LEFT" style="text-align: left;">
		<span><br /></span>
	</p>
	<h3
		id="id-4.ExecuçãodeProceduresemProgramasProgressnoDatasul-4.2.GuiadeProgramação">
		<strong>4.2. Programming Guide</strong>
	</h3>
	<p align="LEFT">
		<strong>WebServices ExecBO</strong> has the following methods:
	</p>
	<div class="table-wrap">
		<table class="confluenceTable">
			<tbody>
				<tr>
					<th class="confluenceTh"><p align="LEFT">Method</p></th>
					<th class="confluenceTh"><p align="LEFT">Description</p></th>
					<th class="confluenceTh"><p align="LEFT">Parameters</p></th>
					<th class="confluenceTh"><p align="LEFT">Return</p></th>
				</tr>
				<tr>
					<td class="confluenceTd"><p align="LEFT">
							<strong>login</strong>
						</p></td>
					<td class="confluenceTd"><p align="LEFT">Enter using a
							user login, obtaining the credentials through the HEADER in the
							SOAP message.</p></td>
					<td class="confluenceTd"><p align="LEFT">It does not
							receive parameters directly, but it gets them through the HEADER
							in the SOAP message, where the following information is informed:</p>
						<p align="LEFT">
							<strong>username</strong>: user name in Datasul
						</p>
						<p align="LEFT">
							<strong>password</strong>: user password in Base64 format.
						</p></td>
					<td class="confluenceTd"><p align="LEFT">
							When successfully logged in, an authentication <strong>token</strong>
							is returned.
						</p>
						<p align="LEFT">When the credentials are invalid, an exception
							is triggered.</p></td>
				</tr>
				<tr>
					<td class="confluenceTd"><p align="LEFT">
							<strong>userLogin</strong>
						</p></td>
					<td class="confluenceTd"><p align="LEFT">
							Same function of the <strong>login</strong> method, but it
							receives the credentials through normal parameters.
						</p></td>
					<td class="confluenceTd"><p align="LEFT">
							<strong>username</strong>: user name in Datasul.
						</p>
						<p align="LEFT">
							<strong>password</strong>: user password in Base64 format.
						</p></td>
					<td class="confluenceTd"><p align="LEFT">
							When successfully logged in, an authentication <strong>token</strong>
							is returned.
						</p>
						<p align="LEFT">When the credentials are invalid, an exception
							is triggered.</p></td>
				</tr>
				<tr>
					<td class="confluenceTd"><p align="LEFT">
							<strong>callProcedure</strong>
						</p></td>
					<td class="confluenceTd"><p align="LEFT">
							It performs a procedure in a BO Progress, receiving the
							authentication <strong>token</strong> through the HEADER in the
							SOAP message.
						</p>
						<p align="LEFT">
							At the HEADER, add the <strong>usertoken</strong> parameter.
						</p></td>
					<td class="confluenceTd"><p align="LEFT">
							<strong>programName:</strong>String – BO or Progress program
							name. This program should be in a folder indicated in the
							AppServer PROPATH. If it is in a sub folder, it must be indicated
							next to the program name.
						</p>
						<p align="LEFT">
							<strong>procedureName:</strong>String – name of the procedure to
							be performed.
						</p>
						<p align="LEFT">
							<strong>jsonParams:</strong>String – string in JSON format
							containing procedure parameters.
						</p></td>
					<td class="confluenceTd"><p align="LEFT">String in JSON
							format with the results of the procedure execution.</p></td>
				</tr>
				<tr>
					<td class="confluenceTd"><p align="LEFT">
							<strong>callProcedureWithToken</strong>
						</p></td>
					<td class="confluenceTd"><p align="LEFT">
							The same function as the <strong>callProcedure</strong> method,
							but the authentication <strong>token</strong> is sent as a normal
							method parameter.
						</p></td>
					<td class="confluenceTd"><p align="LEFT">
							<strong>token</strong><span>:String – authentication
								token.</span>
						</p>
						<p align="LEFT">
							<strong>programName:</strong> – String – BO or Progress program
							name. This program should be in a folder indicated in the
							AppServer PROPATH. If it is in a sub folder, it must be indicated
							next to the program name.
						</p>
						<p align="LEFT">
							<strong>procedureName:</strong> – String – name of the procedure
							to be performed.
						</p>
						<p align="LEFT">
							<strong>jsonParams:</strong> – String – string in JSON format
							containing procedure parameters.
						</p></td>
					<td class="confluenceTd"><p align="LEFT">String in JSON
							format with the results of the procedure execution.</p></td>
				</tr>
			</tbody>
		</table>
	</div>
	<p>&#160;</p>
	<p align="LEFT">
		<span>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. </span><span>In Javascript, we can
			use the </span>function<strong>btoa()</strong><span>, according to
			the following example:</span>
	</p>
	<pre>var pwd64 = btoa("framework");</pre>
	<p>&#160;</p>
	<p align="LEFT">
		<span>The parameter </span><strong>jsonParams </strong><span>from
			the methods </span><strong>callProcedure</strong><span> or </span><strong>callProcedureWithToken</strong><span>
			shall contain the </span><strong>procedure parameters</strong><span>
			in JSON format. In this way, the string </span><strong>jsonParams</strong><span>
			should represent an </span><strong>Array</strong><span> of objects,
			where each object contains the following attributes:</span>
	</p>
	<ul>
		<li><p align="LEFT">
				<strong>name</strong><span>: parameter name, matching the
					Progress procedure. </span>
			</p></li>
		<li><p align="LEFT">
				<strong>type</strong><span>: parameter type, which may be:
					"input", "output" or "input-output". </span>
			</p></li>
		<li><p align="LEFT">
				<strong>dataType</strong><span>: data type, which may be:
					"character", "integer", "decimal", "logical", "date", "datetime" or
					"temp-table". </span>
			</p></li>
		<li><p align="LEFT">
				<strong>value</strong><span>: parameter value. </span><br />
				<span><br /></span>
			</p></li>
	</ul>
	<p align="LEFT">
		<span>Assume a program named </span><strong>Test. p</strong><span>
			with a procedure named </span><strong>sum</strong><span>. This
			procedure receives two </span><strong>integer</strong><span> values
			as </span><strong>input</strong><span> parameters, it sums them and
			returns an </span><strong>integer</strong><span> as </span><strong>output</strong><span>.
			The call for the </span><strong>callProcedure</strong><span> in Java
			would be as follows: </span>
	</p>
	<pre>String result = endpoint.callProcedure(“Teste.p”, “soma”, params);</pre>
	<p>&#160;</p>
	<p align="LEFT">
		Where <strong>params</strong> could have the following value:
	</p>
	<pre>[{"dataType":"integer","name":"value1","value":55,"type":"input"},</pre>
	<pre> {"dataType":"integer","name":"value2","value":99,"type":"input"},</pre>
	<pre> {"dataType":"integer","name":"result","value":0,"type":"output"}]</pre>
	<p>&#160;</p>
	<p align="LEFT">
		The method return is also an ABLTO list. In this example, the value of
		the <strong>result</strong> variable would be:
	</p>
	<pre>[{"dataType":"integer","name":"result","value":154,"type":"output"}]</pre>
	<p>&#160;</p>
	<p align="LEFT">Now let's see an example of calling a procedure
		that receives a temp-table as a parameter and returns it populated.</p>
	<pre>String result = endpoint.callProcedure(“Teste.p”, “getPaises”, params);</pre>
	<p>&#160;</p>
	<p align="LEFT">
		Where <strong>params</strong> has the JSON string with the declaration
		of the following TEMP-TABLE:
	</p>
	<div class="code panel pdl" style="border-width: 1px;">
		<div class="codeContent panelContent pdl">
			<pre class="theme: Eclipse; brush: plain; gutter: true"
				style="font-size: 12px;">DEFINE TEMP-TABLE ttPais
   FIELD code AS CHARACTER LABEL Code
   FIELD name AS CHARACTER LABEL Name.</pre>
		</div>
	</div>
	<p align="LEFT">&#160;</p>
	<p align="LEFT">
		JSON String at TEMP-TABLE <strong>ttPais</strong>:
	</p>
	<pre>[{"name":"ttPais",</pre>
	<pre>  "type":"input-output",</pre>
	<pre>  "dataType":"temptable",</pre>
	<pre>  "value":{"name":"ttPais",</pre>
	<pre>           "fields":[{"name":"codigo","label":"Codigo","type":"integer"},</pre>
	<pre>                     {"name":"nome","label":"Nome","type":"character"}],</pre>
	<pre>           "records":[]</pre>
	<pre>          }</pre>
	<pre>}]</pre>
	<p>&#160;</p>
	<p align="LEFT">The return can be the following JSON string:</p>
	<pre>[{"name":"ttPais",</pre>
	<pre>  "type":"input-output",</pre>
	<pre>  "dataType":"temptable",</pre>
	<pre>  "value":{"name":"ttPais",</pre>
	<pre>           "fields":[{"name":"codigo","label":"Codigo","type":"integer"},</pre>
	<pre>                     {"name":"nome","label":"Nome","type":"character"}],</pre>
	<pre>           "records":[{"codigo":55,"nome":"Brasil"},</pre>
	<pre>                      {"codigo":1,"nome":"USA"},</pre>
	<pre>                      {"codigo":33,"nome":"Italia"},</pre>
	<pre>                      {"codigo":15,"nome":"Canada”}]</pre>
	<pre>          }</pre>
	<pre>}]</pre>
	<p>&#160;</p>
	<h4
		id="id-4.ExecuçãodeProceduresemProgramasProgressnoDatasul-ParaobteroWSDLdoserviçoutilizaraseguinteURL:">In
		order to obtain the WSDL for the service, use the following URL:</h4>
	<p>&#160;</p>
	<pre>
		<a href="http://server" class="external-link" rel="nofollow">http://server</a>:port/wsexecbo/WebServiceExecBO?wsdl</pre>
	<p>
		Where <strong>server:port </strong>is Datasul’s server and port.<strong><br /></strong>
	</p>
	<p>&#160;</p>
	<h4
		id="id-4.ExecuçãodeProceduresemProgramasProgressnoDatasul-ExemplodeChamadaaoServiçoExecBOatravésdeumProcessonoFluig">
		<strong>Example of a Call to the ExecBO Service through a
			Process in Fluig</strong>
	</h4>
	<p align="LEFT" style="margin-left: 28.8px;">
		<span>Through </span><span><strong>Fluig Studio</strong></span><span>,
			register the service </span><span><strong>WSExecBO</strong></span><span>&#160;</span><span>according
			to the steps</span><span> below:</span>
	</p>
	<p align="LEFT" style="margin-left: 29.7667px;">
		<span><strong>a.</strong></span><span> From the </span><span><strong>Fluig
				view, </strong></span><span>select the Preview Service tab </span><span>and
			then </span><span><strong>Include Service</strong></span><span> as
			shown in figure 3.2 a.</span>
	</p>
	<p style="margin-left: 19.2px; text-align: center;">
		<img class="confluence-embedded-image image-center"
			src="http://tdn.totvs.com/download/attachments/81789185/screen3.png?version=2&modificationDate=1380891568000&api=v2"
			data-image-src="http://tdn.totvs.com/download/attachments/81789185/screen3.png?version=2&modificationDate=1380891568000&api=v2"><strong>Figure
			3.2.a</strong>
	</p>
	<p style="margin-left: 19.2px;">&#160;</p>
	<p align="LEFT" style="margin-left: 29.7667px;">
		<span><strong>b. </strong></span><span>Register the new service
			similar to figure 3.2. b.</span>
	</p>
	<p style="margin-left: 19.2px; text-align: center;">
		<img class="confluence-embedded-image image-center"
			src="http://tdn.totvs.com/download/attachments/81789185/screen4.png?version=1&modificationDate=1380891589000&api=v2"
			data-image-src="http://tdn.totvs.com/download/attachments/81789185/screen4.png?version=1&modificationDate=1380891589000&api=v2"><strong>Figure
			3.2.b</strong>
	</p>
	<p style="margin-left: 19.2px;">&#160;</p>
	<p align="LEFT" style="margin-left: 30.7167px;">
		<span><strong>c.</strong></span><span> Select the <strong>Service
				Query</strong> option to test communications with the <strong>WebServices
				ExecBO</strong> and list the available operations, as shown in figure 3.2.c.
		</span>
	</p>
	<p style="margin-left: 0.966667px; text-align: center;">
		<img class="confluence-embedded-image image-center"
			src="http://tdn.totvs.com/download/attachments/81789185/screen5.png?version=1&modificationDate=1380891739000&api=v2"
			data-image-src="http://tdn.totvs.com/download/attachments/81789185/screen5.png?version=1&modificationDate=1380891739000&api=v2"><strong>Figure
			3.2.c</strong>
	</p>
	<p style="margin-left: 0.966667px;">&#160;</p>
	<p align="LEFT" style="margin-left: 28.8px;">
		<span><strong>d.</strong></span><span> 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 </span><span><strong>afterTaskSave</strong></span><span>
			of a process can be seen below. </span>
	</p>
	<div class="code panel pdl" style="border-width: 1px;">
		<div class="codeContent panelContent pdl">
			<pre class="theme: Eclipse; brush: javascript; gutter: true"
				style="font-size: 12px;">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);
   }
}
</pre>
		</div>
	</div>
	<p align="LEFT" style="margin-left: 28.8px;">
		<span><br /></span>
	</p>
	<pre>    </pre>
</div>