Web / API

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

Info

The default Incoming queue is located inside C:\ProgramData\Scanshare\Incoming\Workflow-ID.

Warning

The variable file is specifically linked to the Workflow for which it has been created for security reasons. If moved into a different Workflow it will not be parsed and generate a Bad Data error at the start of processing.

Warning

The Web / API module doesn’t delete itself the document from the Web Service but just execute the configured calls. It is up to the Web Service to make sure the same document doesn’t get downloaded again or up to the calls configuration to specify filters or configure calls to remove the document.

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.

General#

Server Type
Select the type of API calls to use. Available options are:

• Web Services (SOAP)

URL
Enter the Web Service endpoint URL where the API are available.

Namespace
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.

Document decode
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:

• Base64

Skip processing
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.

Info

When Skip Processing is enabled any file format downloaded will be picked up.

Info

This Skip Processing option affects only documents captured by the Web / API module. Documents captured by any other capture module of this workflow will be processed normally unless Workflow Skip Processing is enabled.

Calls#

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.

Call#

Method
The Web Service SOAP method to execute. This refers to the exact SOAP method name as appears in the Web Service WSDL.

Payload
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.

Response Namespace
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.

Response Check
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:

PARAMETERNAME=VALUETOCHECKFORSUCCESS

When not specified all responses are success as far the web request will return a generic HTTP success code.

Response Message
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.

Response Document
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.

Response Filename
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.

Response Data
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:

VARIABLENAME=XMLPARAMETERTOSET

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.

Authentication#

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.