Capture module Web / API allows to capture documents and metadata from an external third party Web Service accessible via a common API.
The module connects to the Web Service by using the specified API defined in the settings, it attempts to download the document from the provided endpoint and, if existing, also additional metadata. The downloaded documents and data are then queued in the current Workflow incoming queue for processing.
For each downloaded document the Web / API module will create a document into the target Workflow incoming queue. The document is composed by two files:
- WEB_XXX.file: the document itself in the original format provided by the Web Service, where XXX is a random generated number
- .var: the variables, if provided as well, by the Web Service
The module creates custom variables during processing. Check the Variables list for more details.
The left hand side menu shows the available settings sections. Settings are displayed according the selected section.
Select the type of API calls to use. Available options are:
- Web Services (SOAP)
Enter the Web Service endpoint URL where the API are available.
Enter the namespace to set in the SOAP calls made to the target Web Service. When namespace of the SOAP calls is customized calls may not succeed if it is not correctly set.
Select the encoding form in which the document will be transferred by the Web Service. The Web / API module will decode the data stream according the selected decode method. Available options are:
If enabled the workflow will be processed by skipping all document processing options for the documents downloaded by the target Web Service. The source document will be treated as a file and never attempted to be read and / or modified, any processing module inside the workflow will be skipped and any connectors will be skipping the output profile processing by using only the untouched original file.
This section allows to define all the web calls to execute on the target Web Service, they will be executed in cascade and the last one will be the one assumed to finally get the document and the variable. This for all cases where multiple cross calls needs to be made. Every call can pass the query result parameter to the next one.
There is no limitation in the number of calls which can be configured as far as the last call is the one configured to download the document and the metadata, if available. When running the last call the Web / API module will expect to download the document, otherwise processing will not start and Workflow will be queued again assuming there are no documents to process.
Calls settings are related to the Server Type selected above in order to perform the type of API calls specified towards the target Web Service.
The Web Service SOAP method to execute. This refers to the exact SOAP method name as appears in the Web Service WSDL.
The XML full payload to send in the request to the Method specified above. The payload needs to include the namespace specified in the general Web Service settings, if any.
The namespace of the response calls if they use a different namespace. When namespace of the calls is customized calls may not be decoded if it is not correctly set.
Parameter, in the response payload, to check for the result of the call (if any). The setting can be used to validate the result server side where the Web Service can return the result in any custom parameter in the response payload. The Web / API module will check the parameter value specified to assume the response needs to be treated as success or failure.
The setting is the form:
When not specified all responses are success as far the web request will return a generic HTTP success code.
Additional parameter, in the response payload, which contains a returned message to log as error when the previous Response Check fails. The setting expects just the parameter name as appearing in the response payload, its value will be used as message to log.
The parameter, in the response payload, which contains the data stream of the document which has been download with the request or the result of the call to pass to the next call.
If this call is not the last one the value of this parameter will be used inside the next call in order to be able to cascade calls when a specific sequence of calls is required to obtain finally the document. The value will be used where the tag %PARAMETER% is inserted inside the payload of the next call. If the parameter appears multiple times in the response payload the next calls are performed the same number of times by using one parameter in each call.
If this is the last call the value of this parameter will be assumed to be the document data stream, hence it will be extracted and decoded according the Document Decode type specified in the general settings above.
The parameter, in the response payload, which contains the filename to use for the downloaded document, if any. If not specified or empty the filename notation mentioned above will be used.
The parameter, in the response payload, which contains the metadata or in general any additional data to download and associate to the current document.
The parameter is in the form:
Where the XMLPARAMETERTOSET is the parameter in the response payload which will be extracted fully and inserted in the VARIABLENAME which will be available during the Workflow processing.
The module doesn’t attempt to parse the contents of the XMLPARAMETERTOSET but just provide it in the Workflow. It is up to the configurator, who should knows what the Web Service returns, to further read, parse and / or elaborate the data returned here, if any.
Username and Password
Enter a username and password if the Web Service requires authentication in order to execute the configured calls.
Authentication is performed as Basic Web Authentication, username and password are encoded and passed in the Basic Authorization header of the requests.