The Web Service Receive Component allows you to receive incoming web service calls from a SQL Server Integration Services control-flow. Messages can be processed synchronously by waiting for the component to finish
blocking on receipt of a message, or asynchronously by handling the
OnReceiveMessage event.
The BlueSSIS Web Service Gateway application
To use this component you must first configure the
BlueSSIS Web Service Gateway application, the installer for which is installed with BlueSSIS and can be located in this Start menu under the BlueSSIS group. This installer can be copied to other machines as required.
The
BlueSSIS Web Service Gateway application is a web application that runs on Microsoft Internet Information Services (IIS) version 6 or later, and exposes a web service interface. Incoming web service messages are then placed into a SQL Server Messaging database for retrieval by the BlueSSIS Web Service Receive component, and a response can also be returned by the
Web Service Respond component to be returned to the caller.
On installing the BlueSSIS Web Service Gateway, you will initially be prompted to enter a name for your web service, and to select an IIS Web Site, a virtual directory and an application pool for the web service to run in.
Towards the end of the installation you will be prompted via a wizard to enter details about your web service :
On this page you specify the name of the web service, along with whether you want to use WCF (Windows Communications Framework). You must also specify connection details to a SQL Server messaging database here (click the
browse button to create one) - note that this is the same database format used
for AS2 and MLLP messages and can be shared between components. If you don't specify an explicit user account to connect to the database you must ensure that the Application Pool used has database access, and a link is provided to automate this process.
Step 3 is to specify details about the parameters and return values of your web service. Web services can have a single primitive input and an optional single return value, or you can select the Typed Schema option to define more sophisticated Xml. Where the web service has a return value you can specify whether the call is synchronous or 'Token / Reponse' - in this latter case the caller polls back to get the response when it is ready. Responses are sent back to the web service by the
Web Service Respond component.
Step 4 allows you to optionally create a WSE3 file for tailored security, or customize the configuration Xml if you are defining a WCF service.
Finally, step 5 allows you tp specify the queue name to be used for messages received from this web service. The Web Service Receive component allows you to filter messages by queue name. You can also flag that incoming HL7 version 3.x messages should be automatically acknowledged.
The Web Service Receive Component
To receive a message from an incoming web service call, simply drag an instance of the Web Service Receive Component onto the control-flow surface. The following interface is presented :
You simply need to specify a variable (string or object) to receive the message content, an optional variable to receive the message identifier (required if you want to respond to the message), an optional variable to receive any header content, and an ADO.Net connection to the Messaging database configured for the BlueSSIS Web Service Gateway. You may also want to edit the queue name if you changed this when configuring your service. Note - messages are generally assumed to be in text form unless your Message
variable is of type Object, in which case the message is retrieved as a binary
array (byte[]). Conversion between text and binary representations is
performed as required according to the Encoding property, accessible only
through the SQL Server Integration Services Property window.
The Timeouts tab allows you to specify timeout information - specifically how long the component should wait to receive a message, and how frequently it should check.
There are two modes of operation - synchronous and asynchronous. In
synchronous mode the task effectively blocks until a web service call is received, whereupon
it completes and linked tasks can execute. In asynchronous mode you would
typically handle the
OnReceiveMessage event
exposed by the component to handle messages as they arrive. This event has
no parameters, as the received message is already bound to a variable.
The
Delay between poll attempts field allows you to configure the number
of seconds between successive checks on the messaging database to determine if
any matching messages have arrived. The
Get timeout field is the
total number of seconds for the component to wait for a message to arrive before
giving up. The
Fail task on Get timeout option allows you to
determine if such a state should trigger a failure of the component.
Otherwise you can check if a file was retrieved by checking the Message variable
(which will have empty content if no message was retrieved) or using the
ExecValueVariable result.
0 and -1 are special cases for
Get timeout, relating to a zero or
infinite timeout respectively. In the case of a zero timeout, this means
that the component will not wait if there is no message waiting in the messaging
database.
To send a response to a received web service message, use the
Web Service Respond component.
Note that you can also execute this task within a Foreach Loop Container task, to execute the contained tasks once for every file retrieved. Simply select 'BlueSSIS +Web Service Receive Enumerator' as the Enumerator, then click the 'Configure...' button to configure the properties.
BlueSSIS provides a number of enumerators, mostly mapping to associated data retrieval tasks, but also including an Infinite Loop enumerator (useful for manual polling scenarios).