The Call Web Service Smart Service allows you to integrate data from web services within your process and automatically create a custom data type with it. This allows for more flexible mapping of web service inputs and outputs.
The error messages returned by this activity may help diagnosis problems you could encounter during process design and execution.
When creating a custom data type, there are certain restrictions on the data types that can be created.
If you encounter an unavailable web service or a request timeout (503 or 408 error) at runtime, the call is automatically retried.
See also: Automatic Error Handling
The user must be a member of the Process Model Creators group in order to configure the WSDL URL for this smart service.
Category: Integrations & APIs
Assignment Options: Unattended/Attended
This section contains tab configuration details specific to this smart service. For more information about common configurations see the Process Node Properties page.
If you need to connect to this web service using a proxy server that configuration can be enabled in the Admin Console.
The following configurations options are available to choose your web service:
Dynamic WSDL URL: Type in, use the Expression Editor, or select the dynamic WSDL URL from the UDDI directory.
If using a dynamic WSDL URL, you must create your data structures at design time.
Username, Password, and Domain: Credentials for the WSDL URL. (Use the optional domain field for NTLM.)
Remote web services can temporarily cache the provided credentials after being called from the smart service the first time. It is important to always provide credentials to web services that require authentication, even if you find that testing the web service without sending credentials works. The credentials might be cached on the remote server.
Invalid HTTP Header <Keys/Values> provided in ... [node name]. Keys and Values must be expressed in array notation or as Process Variables that accept multiple values (an Array).
Once you've configured these settings, click Get Services to test the URL.
RPC/encoded service styles are not supported, and instead you must use RPC/literal or Document/literal encodings. If you know the WSDL is valid, and you receive an Invalid WSDL exception, check to ensure that the
<definition> or the
<description> element appears within the first 2 KB of data in the WSDL file. WSDL versions 1.1 and 2.0 and SOAP 1 versions .1 and 1.2 are supported. Appian reads and parses the WSDL using Apache AXIS2. It is validated against WS-I Basic Profile 1.1.
If the WSDL URL validates, the following fields appear:
Service: The web service(s) listed in the WSDL are displayed. If multiple services are available, select the desired service.
Endpoint: The particulars of a service, which include the Endpoint name and the binding (Endpoint Address is not supported). If multiple Endpoints are available for a service, select the desired Endpoint.
Binding: The Endpoint binding, which is either HTTP or SOAP. It is taken from the Endpoint and cannot be selected.
Operation: The available web service operations. If multiple operations are available, select the desired operation.
Any custom data type used by the web service selected as the Operation are created if they are explicitly defined in the WSDL. System data types are mapped to standard Appian data types.
Any data type creation errors or warnings are commonly due to custom data type creation restrictions. If the service requires authentication and header information, the Service Invocation Options group box appears.
If a WSDL references custom data types that aren't explicitly defined (assumed to be known by the web service publisher) you must define the missing data types in an XSD file and have an Appian system administrator import the XSD.
Custom data types automatically created from WSDLs should always be added to and deployed with the application package.
See also: Application Deployment
When using the Call Web Service node, the custom data types are generated when the node is configured for the first time and the model is saved and published. Appian does not recreate the custom data types on every execution of the web service.
If the WSDL definition changes such that the data types need to be updated, click the "Refresh Services" button on the node. Clicking this button will update the existing data types to match the new WSDL definition and update all of the dependents of the data types to point to the new versions. The process model needs to be published for these changes to take effect. Clicking "Refresh Services" and not publishing the process model can have unintended performance consequences. Dependent data stores' schema will not be updated with this change, even if automatic schema updates are enabled.
Alternatively, republishing the process model will accomplish the same thing.
You can also download the XSD from the Data Type Designer or copy the XSD from the WSDL URL, then make manual edits and import the XSD. We do not recommend this approach, but if the WSDL definition contains complex content restrictions, you will need to do remove them before creating the new version of the data type.
If you delete WSDL data types, your data types will be automatically refreshed after internal caches expire or after an application server restart. If fields were changed or removed, you could see behavior changes in dependent objects after this refresh. Therefore, you should never delete WSDL data types.
Data transferred using web services are only encrypted when the web service is running over HTTPS. Appian recommends all sensitive or confidential data be encrypted. Application-level security is the responsibility of each customer.
The call web service node supports TransportBinding policy assertions that require HTTPS, requiring a client certificate or specific authentication schemes listed below. Web service security settings must allow username, password, and/or domain authentication.
Web service providers that support basic auth, digest, NTLM, or WS-Security UsernameToken 1.1 or 1.0 authentication are supported. For UsernameToken authentication, username-only, username and plaintext password, and username and password digest are supported.
Transport layer authentication mechanisms (basic auth, digest, NTLM, client certificate) may be declared by the WSDL using TransportBinding WS-Policy assertions, however such a declaration is not required. Any WS-Policy assertions for these transport layer authentication mechanisms that are not declared as TransportBinding WS-Policy assertions are not supported.
In order to use WS-Security UsernameToken, it must be declared in the WSDL as a WS-Policy assertion. If the WSDL contains multiple policy alternatives in an ExactlyOne element, the first alternative supported by Appian will be selected.
Note: Web service providers that use the Apache Rampart library earlier than version 1.7 may produce a WSDL that is invalid in terms of how the UsernameToken assertion is presented. This can lead to the Call Web Service smart service interpreting the WSDL as requesting the username and plain text password to be sent instead of a digest/hashed password. See the Apache issue tracking item RAMPART-384 for more details.
If the WSDL for the web service declares that UsernameToken is supported for authentication, a "WSDL Policy" section will be revealed on the setup tab. Credentials can be provided in one of two ways:
password respectively in order for them to be detected and used by the Call Web Service smart service for UsernameToken credentials. A radio button toggle is provided to allow selection between the site-wide credentials for the external system, or the per-user credentials of the assignee that executes the smart service. If the credentials of the assignee are selected, the node must be attended or will pause by exception during execution.
You can connect to a single Appian process model published as a web service. Only one process model per Appian installation can be consumed by the call web service activity. The same name/namespace are used to expose the parameters for all models.
WSDLs that utilize data types with the following XSD constructs result in CDTs that ignore the construct:
The following types of web service cannot be called using this smart service:
For more information about specific XSD elements and whether or not they are supported, see the Supported XSD and JPA Annotations page.
Most of the node inputs take their value from the configurations you made on the Setup tab.
Any custom data types created for the web service automatically appear as Node Inputs. Node Inputs for custom data types include nested elements. Click + to view the elements of a custom Node Input and enter your web service inputs in to the Value field of each element.
The following node input is available for configuration regardless of the web service.
|Pause Node on HTTP Error
|Determines whether the smart service should pause by exception if it receives an HTTP error.
If set to
false and an HTTP error occurs, the node completes and populates the node outputs for HTTP Error Occurred and HTTP Status Code as well as any other configured.
Most of the node outputs on the Outputs tab depend on the web service you're using. The node outputs below are the only ones that are available by default.
|HTTP Error Occurred
true if an HTTP error occurred, otherwise
|HTTP Status Code
|The HTTP status code that was returned.
If an HTTP error occurs and you allow the node to complete, you can use these outputs to determine how the process handles the error, such as incorporating an escalation into a later part of the process design. For those error responses that are handled by automatic retry (408 and 503), the node will complete or pause by exception after the final retry has failed.
.NET data sets
Some .NET-based web services return a .NET DataSet type object. Since the structure of the DataSet object is not known until runtime (it’s not explicitly defined in the WSDL), this smart service allows you to map the result to a process variable of type Text that contains an XML representation of the DataSet object.
xpathsnippet() expression function can then be used to navigate and extract relevant data from the DataSet. This function does not accept UTF-16 encoded data. If the .NET DataSet is UTF-16, use the
substitute() function to replace any references to UTF-16 with UTF-1.
Large data sets
Ensure that the space used by the Process Execution and Process Analytics engines is used only for valuable data - not for any extraneous data returned the web service.
When you expect to return a large amount of data, place this smart service into a subprocess along with other nodes used to parse the data, then configure the subprocess in the following manner:
When using a large data set in other process nodes, you might need to adjust the limits on how much data can be entered into a field.
See also: Configuring a Subprocess Activity
To save values from a nested array of web service data, you must save the parent object into a process variable. This is possible, even if the imported custom data type remains hidden.
Result versus the parent
Results. You can select an array, but multiple records within it are outside the reach of this view.
Keep in mind that the web service created a data type used to catch the web service data in Node Inputs or Node Outputs and for the process variable. This data type cannot be used for other process variables, rule inputs, or data in other nodes until the data type is made available in pickers.
In order to handle certain values from a web service, you may want to create a new variable that matches the node containing the desired data.
The Call Web Service Smart Service automatically creates the data types used by your web service, which can be unhidden for the creation of a process variable that matches the desired node.
After the process variable is created, that data type can be safely hidden without impacting your new process variable.
Call Web Service Smart Service