User Tools


Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Next revision
Previous revision
en:adminmanual:businessmappings:webservicecall [2019/10/28 17:46]
gledisabaci
en:adminmanual:businessmappings:webservicecall [2020/02/21 00:04]
joebordes [An example of two tasks passing context]
Line 1: Line 1:
-====== REST/SOAP call and retrieval Mapping ​======+===== REST/SOAP call and retrieval Mapping =====
  
-Added a new task type in workflows ​"Run Web Service"​. To use this task type we should use new map with a new mapping type "​Webservice Mapping"​.+This workflow ​task type, named "**Run Web Service**" ​can be used to launch ​REST or SOAP call to another system and retrieve the results to be saved in fields of coreBOS or to be passed along the workflow set of tasks to be consumed in other workflow tasks by using the **getContext** function.
  
-{{:​en:​adminmanual:​businessmappings:​1.png?400|}}+To use this task type we need a map of type **Webservice Mapping**. This map must be selected in the workflow task.
  
-In the pertinent ​task can be attached ​just one map. If we click on '​+'​ button we can see a list of all "Webservice ​Mapping" ​maps(defines the webservice ​method parameters that will be launched).+{{:​en:​adminmanual:​businessmappings:​1.png|}} 
 + 
 +In the task, we can attach ​just one map which can be selected using the input field. 
 + 
 +{{:​en:​adminmanual:​businessmappings:​2.png|}} 
 +{{:​en:​adminmanual:​businessmappings:​3.png|}} 
 + 
 +The "**Web Service ​Mapping**" defines the web service ​method parameters that will be launched ​and is divided into three sections: 
 + 
 +  * **wsconfig** where we define the necessary settings to make the call 
 +  * **fields** which define the parameters of the call and will permit us to capture values from the coreBOS application 
 +  * **Response**
   ​   ​
-{{:en:adminmanual:​businessmappings:​2.png?400|}} +====== wsconfig ====== 
-{{:​en:​adminmanual:​businessmappings:​3.png?400|}}+ 
 +  * <​wsurl>​Endpoint where we send the data</​wsurl>​ 
 +  * <​wshttpmethod>​GET,​ PUT, POST, DELETE</​wshttpmethod>​ 
 +  * <​methodname>​define the method that should be called</​methodname>​ 
 +  * wsuser and wspass in case the service uses these 
 +  * wsheader contain keyname and keyvalue pairs with information that must be sent in the header of the call 
 +    * a special header is "​Authorization",​ this keyname accepts a special syntax in it's keyvalue**getContext(variable_name)**. this expression will search for the variable_name in the workflow context and use that instead of the hard coded value which can be set here also. 
 +  * <​wstype>​REST or SOAP</​wstype>​ 
 +  * <​inputtype>​XML/​URL/​JSON/​URLRESTFUL</​inputtype>​ 
 +  * <​outputtype>​JSON or XML</​outputtype>​ 
 + 
 +Most of the directives are self-explanatory but there are a few that need to be explained due to the process they have related. 
 + 
 +The **INPUTTYPE** defines how we will send the parameters (fields) to the end-point: 
 + 
 +  * XML and JSON will be set in the body of the callThe XML value will be urlencoded 
 +  * URL will have the values added in the URL as GET parameters 
 +  * URLRESTFUL will search the wsurl directive for variables defined in the fields section preceded with a dollar sign. If they are present they will be substituted by the calculated value. 
 + 
 + 
 +If the **OUTPUTTYPE** is JSON two additional tasks are performed: 
 + 
 +  * if the Response section has a "​field"​ value for the response then we will save the value received from the call in the indicated field 
 +  * all the Response values received will be put into the workflow context. If no name is given in the Response section for the variable in the context the application will use the name of the variable returned preceded by the text **wsctx_** 
 + 
 + 
 +====== fields ====== 
 + 
 +  * <​fields>​block that contains the input parameter fields</​fields>​ 
 +  * <​fieldname>​input parameter for REST/SOAP call</​fieldname>​ 
 +  * <​OrgfieldName>​fieldname in coreBOS where we get the input parameter value</​OrgfieldName>​ 
 + 
 +this section is processed by the same engine that is used in the [[en:​adminmanual:​businessmappings:​mapping|Field Mapping Business Map]] so we can use all the options that we have there like Expressions and Rules 
 + 
 + 
 +====== Response ======
  
-GET, PUT, POSTDELETE methods are supported.+  * <​Response>​ block that contains the response fields coming from the call and where we have to save the values </​Response>​ 
 +  * <​fieldname>​ the value we get back from web service call </​fieldname>​ 
 +  * <​destination><​field>​ fieldname in coreBOS to update with the WS response </​field></​destination>​ this directive is optional. If it is not given or is set to an empty valuethe field will not be updated. 
 +  * <​destination><​context>​ the name to use to set this value in the workflow context </​context></​destination>​ if none is given we will use **wsctx_{fieldname}**
  
 +====== Examples ======
  
-An example of Map for SOAP Call:+=====An example of Map for SOAP Call:=====
  
 <code XML> <code XML>
-<?xml version="​1.0"​ encoding="​utf-8"?>​ 
 <map> <map>
 <​originmodule>​ <​originmodule>​
-<​originname>​Contacts</​originname>​+<​originname>​Accounts</​originname>​
 </​originmodule>​ </​originmodule>​
 + 
 <​wsconfig>​ <​wsconfig>​
-<​wsurl>​http://​www.holidaywebservice.com/Holidays/US/USHolidayService.asmx?wsdl</​wsurl>​+<​wsurl>​http://​ec.europa.eu/taxation_customs/vies/checkVatService.wsdl</​wsurl>​
 <​wshttpmethod>​POST</​wshttpmethod>​ <​wshttpmethod>​POST</​wshttpmethod>​
-<​methodname>​GetHolidaysForYear</​methodname>​+<​methodname>​checkVat</​methodname>​
 <​wsresponsetime></​wsresponsetime>​ <​wsresponsetime></​wsresponsetime>​
-<​wstype>​SOAP</​wstype>​ 
 <​wsuser></​wsuser>​ <​wsuser></​wsuser>​
 <​wspass></​wspass>​ <​wspass></​wspass>​
Line 32: Line 81:
 <​wsproxyport></​wsproxyport>​ <​wsproxyport></​wsproxyport>​
 <​wsheader>​ <​wsheader>​
-<​header>​ +<​header>​  
-<​keyname>​Content-type</​keyname>​ +<​keyname>​Content-type</​keyname>​  
-<​keyvalue>​application/​json</​keyvalue>​+<​keyvalue>​application/​json</​keyvalue> ​
 </​header>​ </​header>​
 </​wsheader>​ </​wsheader>​
-<​inputtype>​XML</​inputtype>​ +<​wstype>​SOAP</​wstype>​ 
-<​outputtype>​XML</​outputtype>​+<​inputtype>​JSON</​inputtype>​ 
 +<​outputtype>​JSON</​outputtype> ​
 </​wsconfig>​ </​wsconfig>​
 + 
 <​fields>​ <​fields>​
 <​field>​ <​field>​
-<​fieldname>​year</​fieldname>​+<​fieldname>​countryCode</​fieldname>​
 <​Orgfields>​ <​Orgfields>​
 <​Orgfield>​ <​Orgfield>​
-<​OrgfieldName>​year</​OrgfieldName>​+<​OrgfieldName>​bill_code</​OrgfieldName
 +<​OrgfieldID></​OrgfieldID>
 </​Orgfield>​ </​Orgfield>​
-<​delimiter>​--None--</​delimiter>​+<​delimiter>​</​delimiter>​ 
 +</​Orgfields>​ 
 +</​field>​ 
 +<​field>​ 
 +<​fieldname>​vatNumber</​fieldname>​ 
 +<​Orgfields>​ 
 +<​Orgfield>​ 
 +<​OrgfieldName>​siccode</​OrgfieldName>​ 
 +<​OrgfieldID></​OrgfieldID>​ 
 +</​Orgfield>​ 
 +<​delimiter>​</​delimiter>​
 </​Orgfields>​ </​Orgfields>​
 </​field>​ </​field>​
 </​fields>​ </​fields>​
 + 
 <​Response>​ <​Response>​
 <​field>​ <​field>​
-<​fieldname>​message</​fieldname>​+<​fieldname>​valid</​fieldname>​ 
 +<​destination>​ 
 +<​field>​tickersymbol</​field>​ 
 +</​destination>​ 
 +</​field>​ 
 +<​field>​ 
 +<​fieldname>​requestDate</​fieldname>​ 
 +<​destination>​ 
 +<​field>​ownership</​field>​ 
 +</​destination>​ 
 +</​field>​ 
 +</​Response>​ 
 +</​map>​ 
 +</​code>​ 
 + 
 +=====An example of Map for REST Call:​===== 
 + 
 +<code XML> 
 +<​map>​ 
 +<​originmodule>​ 
 +<​originname>​Accounts</​originname>​ 
 +</​originmodule>​ 
 +  
 +<​wsconfig>​ 
 +<​wsurl>​http://​localhost/​facturascripts/​api/​3/​divisas/​$coddivisa</​wsurl>​ 
 +<​wshttpmethod>​GET</​wshttpmethod>​ 
 +<​methodname>​divisas</​methodname>​ 
 +<​wsresponsetime></​wsresponsetime>​ 
 +<​wsuser></​wsuser>​ 
 +<​wspass></​wspass>​ 
 +<​wsheader>​ 
 +<​header>​  
 +<​keyname>​Content-type</​keyname>​  
 +<​keyvalue>​application/​json</​keyvalue>​  
 +</​header>​ 
 +<​header>​  
 +<​keyname>​token</​keyname>​  
 +<​keyvalue>​0WXmP4nVDIGNHKysuceA</​keyvalue>​  
 +</​header>​ 
 +</​wsheader>​ 
 +<​wstype>​REST</​wstype>​ 
 +<​inputtype>​URLRESTFUL</​inputtype>​ 
 +<​outputtype>​JSON</​outputtype>​  
 +</​wsconfig>​ 
 +  
 +<​fields>​ 
 +<​field>​ 
 +<​fieldname>​coddivisa</​fieldname>​
 <​Orgfields>​ <​Orgfields>​
 <​Orgfield>​ <​Orgfield>​
-<​OrgfieldName>​title</​OrgfieldName>​+<​OrgfieldName>​tickersymbol</​OrgfieldName
 +<​OrgfieldID></​OrgfieldID>
 </​Orgfield>​ </​Orgfield>​
-<​delimiter>​--None--</​delimiter>​+<​delimiter></​delimiter>​
 </​Orgfields>​ </​Orgfields>​
 +</​field>​
 +</​fields>​
 + 
 +<​Response>​
 +<​field>​
 +<​fieldname>​descripcion</​fieldname>​
 +<​destination>​
 +<​field>​ownership</​field>​
 +</​destination>​
 </​field>​ </​field>​
 </​Response>​ </​Response>​
Line 65: Line 185:
 </​code>​ </​code>​
  
-  * <​wsurl>​Endpoint where we send the data</​wsurl>​ +Note how the $coddivisa variable in the URL <code><wsurl>http://localhost/facturascripts/api/3/divisas/$coddivisa</wsurl></codewill be substituted by the actual ​value that we have in coreBOS as defined in the fields ​section. In this case, the value of the tickersymbol field in the Account will be read and $coddivisa will be substituted with that value.
-  * <​methodname>​define ​the method that should be called</methodname> +
-  * <wstype>REST or SOAP</wstype>​ +
-  * <​inputtype>​XML/URL for SOAP; JSON/URL/URLRESTFUL for REST</inputtype>​ +
-  * <​outputtype>​JSON for REST; XML for SOAP</outputtype>​ +
-  * <​fields>​block that contains the input parameter fields</fields> +
-  * <fieldname>​input parameter for REST/SOAP call(in the block fields)</​fieldname> +
-  * <​OrgfieldName>​fieldname in CoreBOS where we get the input parameter ​value</​OrgfieldName>​ +
-  * <​Response>​block ​that contains ​the response ​fields</​Response>​ +
-  * <​fieldname>​the value we get back from ws(in the block Response)</​fieldname>​ +
-  * <​OrgfieldName>​fieldname ​in CoreBOS to update/​insert ​the WS response</​OrgfieldName>​+
  
 +=====An example of two tasks passing context=====
  
-   +This first map executes an authentication call and loads the authorization token into the workflow context and the second task uses that value to make an operation call.
  
 +<code xml>
 +<map>
 +<​originmodule>​
 +<​originname>​Accounts</​originname>​
 +</​originmodule>​
  
 +<​wsconfig>​
 +<​wsurl><​![CDATA[http://​localhost/​corebostsolucio/​webservice.php?​operation=testcontext&​id=2355]]></​wsurl>​
 +<​wshttpmethod>​GET</​wshttpmethod>​
 +<​methodname>​wslogin</​methodname>​
 +<​wsresponsetime></​wsresponsetime>​
 +<​wsuser></​wsuser>​
 +<​wspass></​wspass>​
 +<​wsheader>​
 +<​header>​
 +<​keyname>​Content-type</​keyname>​
 +<​keyvalue>​application/​json</​keyvalue>​
 +</​header>​
 +<​header>​
 +<​keyname>​Authorization</​keyname>​
 +<​keyvalue>​9192929383834</​keyvalue>​
 +</​header>​
 +</​wsheader>​
 +<​wstype>​REST</​wstype>​
 +<​inputtype>​JSON</​inputtype>​
 +<​outputtype>​JSON</​outputtype>​
 +</​wsconfig>​
  
 +<​fields>​
 +</​fields>​
  
 +<​Response>​
 +<​field>​
 +<​fieldname>​result</​fieldname>​
 +<​destination>​
 +<​context>​token</​context>​
 +</​destination>​
 +</​field>​
 +</​Response>​
 +</​map>​
 +</​code>​
  
 +<code xml>
 +<map>
 +<​originmodule>​
 +<​originname>​Accounts</​originname>​
 +</​originmodule>​
 +
 +<​wsconfig>​
 +<​wsurl>​http://​localhost/​corebostsolucio/​webservice.php?​operation=testcontext2</​wsurl>​
 +<​wshttpmethod>​POST</​wshttpmethod>​
 +<​methodname>​wspost</​methodname>​
 +<​wsresponsetime></​wsresponsetime>​
 +<​wsuser></​wsuser>​
 +<​wspass></​wspass>​
 +<​wsheader>​
 +<​header>​
 +<​keyname>​Content-type</​keyname>​
 +<​keyvalue>​application/​json</​keyvalue>​
 +</​header>​
 +<​header>​
 +<​keyname>​Authorization</​keyname>​
 +<​keyvalue>​getContext(token)</​keyvalue>​
 +</​header>​
 +</​wsheader>​
 +<​wstype>​REST</​wstype>​
 +<​inputtype>​JSON</​inputtype>​
 +<​outputtype>​JSON</​outputtype>​
 +</​wsconfig>​
 +
 +<​fields>​
 +<​field>​
 +<​fieldname>​token</​fieldname>​
 +<​Orgfields>​
 +<​Orgfield>​
 +<​OrgfieldName>​accountname</​OrgfieldName>​
 +<​OrgfieldID></​OrgfieldID>​
 +</​Orgfield>​
 +<​delimiter></​delimiter>​
 +</​Orgfields>​
 +</​field>​
 +</​fields>​
 +
 +<​Response>​
 +<​field>​
 +<​fieldname>​description</​fieldname>​
 +<​destination>​
 +<​field>​accountname</​field>​
 +</​destination>​
 +</​field>​
 +</​Response>​
 +</​map>​
 +</​code>​