|
Working with the Web Services Processes Group |
  
|
Working with the Web Services Processes Group
|
Working with the Web Services Processes Group |
|
Process Purpose
Web services allow access to software components through the HTTP standard protocol. The HTTP/Web Services group of processes enables the device to directly call REST compliant Web Services, SOAP compliant Web Services or any http URL.
Most used methods are possible (GET, POST, etc). With this group of processes, it is possible to receive data in JSON and XML formats and to parse them into data files and/or variables.
There is one recurring icon in these processes:
Click this icon (located on the upper right corner of the properties window) to set up a time out. See Time Out below.
A time out is a preset time period during which a task must be completed or that task is canceled. Time outs are particularly useful in a communications context - if the communication between system/application and Host does not occur within a specific period of time, the time out stops the constant connection request loop.
When defining a time out for your application, consider the following time outs:
•The TCP time out - a time out embedded in the target device's OS. It is defined/controlled by the manufacturer and can vary according to the device's OS (external context).
If the TCP time out is shorter than the Process or Host Profile time outs, it will be applied first and dismiss any other defined time out(s).
•The Process time out - the time out you define in a process (MCL-Designer context). It overrides the Host Profile time out.
•The Host Profile time out - the time out you define within the Host Profile(s) you use in Host related processes (MCL-Designer context).
A time out fulfillment always triggers a "Comm Error". You must take into account the TCP time out when you define a Process time out or a Host Profile time out at the risk of triggering a "virtual communications error":
Ex: Considering the TCP time out of a WinCE device of 21 seconds and a Process time out of 60 seconds, a "communications error" will be displayed after 21 seconds.
Ex: Considering the same TCP time out of a WinCE device (21 seconds) and a Process time out of 0 (infinite), the "communications error" will also be displayed after 21 seconds.
Ex: Considering the same TCP time out of a WinCE device of 21 seconds and a Process time out of 10 seconds, the "communications error" will also be displayed after 10 seconds.
Contact the manufacturer to find out/change the device's TCP time out.
The Host Profile time out does NOT apply to Aux related processes that use an Aux profile of the "Socket TCP" type.
Due to limitations of the connection provided by Windows Mobile Device Center (USB connection with the device), the used time out is always the TCP time out.
When establishing a shorter Process time out than a TCP time out to override that TCP time out, always consider the task it is associated to.
Ex: If you define a 2 second time out within a "Receive from Host" process (used to receive data packets from a specific host server), the time out may not be enough to allow the application to contact the host, validate the communication and proceed to data packet exchange. The time out will interrupt the application's workflow and trigger a "virtual" error, meaning, there is no real issue regarding communication between the application and the host but a "Comm Error" will be displayed.
You can associate a Message Box to a time out to inform the operator that this condition occurred for a specific operation and, depending on the application's workflow, you can add the necessary processes/settings to allow the operator to retry that operation.
To Define a Process Time Out
Step-by-step
1. Click (when available). This icon is located on the upper right corner of a properties window. This opens a "Time Out" window.
2. Define the time out value:
Time Out (s) |
|
Time Out |
Use one of the following to define the time out value:
•Enter the number of seconds or use the up/down arrows. •Use the up/down arrows and select "<Default>" to use the time out associated to the selected host profile. ("<Default>" is NOT APPLICABLE to Aux profiles that use "Socket TCP".) •Use the up/down arrows to select "Infinite" or enter "0" for an infinite time out. |
3. Click 
to conclude or 
to abort the operation.
The web service related processes include a few options/windows designed to help you with web service transactions and response data management:
•The "URL Assistant" window defines/constructs the call to a web service. See The URL Assistant below.
•The "Test the Web Service" window tests, retrieves and exposes the response so it can be used by other options. See The Test the Web Service window.
•The "Body to Use for Parsing" window allows for the manipulation of displayed data for a parsing. See The Body to Use for Parsing window.
The purpose for this assistant is to help you define the required parameters in the web service request URL.
Step-by-step
1. Click 
(available to the right of the "URL" text box).
2. Fill in the following options:
Host and Resource Path |
|
Host Name |
Enter the host profile from the drop-down OR click |
Resource Path/ |
Enter the resource path OR click |
Query String |
|
Parameter Name column |
Enter the necessary query parameter(s) OR click the corresponding |
Value column |
Enter the query value(s) OR click the corresponding |
Depending on the process you call the URL Assistant from, you may or may not have the "Test the Web Service" option available (
icon). See The Test the Web Service window.
Ex: This option is NOT available when you open the "URL Assistant" within the "Call & Parse" and "Parse Response" processes because the is already available in the upper right corner of the corresponding properties window.
3. Click to apply your options in the "URL Assistant" window.
The "Test the Web Service" window
This window has multiple purposes. It tests the request to the web service and it retrieves/displays the result of the request, meaning, the response which, in turn, will be fed into another useful window - the "Body to Use for Parsing" window. It does NOT expose the full raw response, it displays arrays and the first 5 elements of each array.
The information displayed by this window is affected by its context. Below are the two types of "Test the Web Service" window:
|
This window opens when it is called from the following HTTP/Web Services processes:
"REST/JSON" "REST/XML" "Get File from URL" "HTTP Request"
It displays the defined URL, corresponding authentication parameters, if required, and resulting web service response.
Most of the fields are automatically filled in once you get the web service's response but you can perform some operations:
I. In the "Display" drop-down ("Response" section), select the appropriate format for the display of information ("HTML", "Raw Text", "XML", "JSON", "Image" or "Hexadecimal").
II. Use the icons on the upper left corner of the window when necessary:
Click |
|
This window opens when it is called from the following HTTP/Web Services processes:
"Call & Parse" "Parse Response"
It displays the web service's response (header and body).
If the URL includes variables, you can define their values. Use the See Detail of a Set Variable Values window.
If you want to refresh the Web Service request, click
Click |
Detail of a "Set Variable Values" window
This window displays all the variables contained in the URL you have defined.
I. Click the field you want to edit so it is set to edit mode.
II. Enter the value you want to add to the variable in the "Value" column.
III. Click to apply and return to the "Test Web Service" window.
The "Body to Use for Parsing" window
This window displays the body of a web service response and is accessed via the 
button which is available in the properties window of the "Call & Parse" and "Parse Response" processes (specifically, in the "Parse Simple" and "Parse to File" tabs).
The displayed information is a result of a web service test (the "Test the Web Service" window feeds the "Body to Use for Parsing" window). In fact, if you perform a web service test (by clicking in the "Call" tab) and, then, proceed to the "Parse Simple" or "Parse to File" tabs, the corresponding "Test the Web Service" window, that was left open, is replaced with the "Body to Use for Parsing" window.
The purpose for this window is to use the highlighted keys (elements in green/arrays in blue) to define the elements to be parsed via a Drag-and-Drop or a right-click option.
Check the example/explanations below to understand the window's usage in each available context.
Examples of "Body to Use for Parsing" Window Usage
Examples A and B illustrate the use of a "Body to Use for Parsing" window in a simple parse of a web service call. Both options are performed within the "Parse Simple" tab of the "Call & Response" process.
Both the "Parse Simple" tab and the "Body to Use for Parsing" window are open. Only the elements displayed in green (keys) are available for a Drag-and-Drop. The "totalResultsCount" key is dragged into the "Path Name" column. The writable variable of the "Store into Variable" column must be entered by hand or via a drop-down selection in the corresponding row.
|
Both the "Parse Simple" tab and the "Body to Use for Parsing" window are open. Instead of a Drag-and-Drop, right-click the key (displayed in green) to be defined as a path and select the "Add Path" option. This adds the selected key onto the "Path Name" column of the "Parse Simple" tab. The writable variables of the "Store into Variable" column are entered one by one in the corresponding rows.
|
Examples C and D illustrate the use of a "Body to Use for Parsing" window in the "parse to file" procedure of a web service response. Both options are performed within the "Parse to File" tab of the "Call & Response" process.
Both the "Parse to File" tab and the "Body to Use for Parsing" window are open. In this case, it is the array "geoname" that is dragged into the "Root Array" box. Once the Drag-and-drop is performed, you get the following window:
Either click If you choose not to fill the "From Sub Path Name" column automatically, you can use the:
Drop-Down - ("Parse to File" tab) In the "From Sub Path Name" column, select the necessary elements from each field's drop-down. Drag-and-Drop - Drag the intended elements (in green) from the "Body to Use for Parsing" window onto the "From Sub Path Name" column. Right-click Menu Option - In the "Body to Use for Parsing" window, right-click the element you want (in green) and select "Add Sub Path". The selected element will be added to the "From Sub Path Name" column. (This option is only available after you have defined the "root array".)
|
Both the "Parse to File" tab and the "Body to Use for Parsing" window are open. Instead of a Drag-and-Drop, right-click the intended array and select the "Set as 'Root Array' " option. Decide how to fill in the related "Sub Path Name" column, in the resulting window.
Either click If you choose not to fill the "From Sub Path Name" column automatically, you can use the:
Drop-Down - ("Parse to File" tab) In the "From Sub Path Name" column, select the necessary elements from each field's drop-down. Drag-and-Drop - Drag the intended elements (in green) from the "Body to Use for Parsing" window onto the "From Sub Path Name" column. Right-click Menu Pption - In the "Body to Use for Parsing" window, right-click the element you want (in green) and select "Add Sub Path". The selected element will be added to the "From Sub Path Name" column. (This option is only available after you have defined the "root array".)
|
See Sample Applications to check for application samples that use Web Service processes.
Certain Web Services require an authentication. This means the host profiles used to connect to such web services must include an authorization profile to handle the necessary authentication information to ensure the MCL application can communicate with that web service. Depending on the web service's authentication requirements, the authorization profile may use the basic/digest authentication or the more complex/secure OAuth 2.0 authorization protocol.
The OAuth 2.0 authentication ensures that the user credentials are not shared with the MCL application - that information is stored in an Identity Server. Basically, the MCL application contacts that server to get confirmation that the user is authorized to access the web service and relays that information to the web service.
If using the OAuth 2.0 authentication in an authorization profile, you must also consider how the authorization profile will handle its contact with the Identity Server, meaning, you must define the contact grants. There are 3 grant types to consider, each one with its security levels/limitations:
•The "Authorization Code" grant type (the recommended industry-standard).
•The "Client Credentials" grant type.
•The "Password" grant type.
For more information on authorization profiles with the OAuth 2.0 authentication method, see Grant Types.
The Web Services group includes the following processes:
----- Web Services |
----- HTTP |
----- Legacy |
----- OAuth 2.0 |
to create a new host profile or edit an existing one. 
and select a variable with that value. See 
Click this icon 
If your defined URL contains variables, click this icon to open a list which includes all the variables contained within the web service's response and insert a value into each variable. See 
to close the window.
and all the array's elements are retrieved and automatically placed in the "From Sub Path Name" column 
and fill in the related "From Sub Path Name" column 
