Greetings from the Scribe Product team. I am Tom OBrien and I am the product manager here at Scribe. One of the many facets of my role includes community relations, and the Scribe Blog will be a great way for me to solicit feedback from the community (by the way, you can always reach me and the entire product management team by sending an email to productmanagment at scribesoft.com). This post will outline some of the more advanced features of the Web Service adapter and I invite you to post comments for any questions or suggestions you might have about this post and its related content.
As many of you heard, we released v1.0 of our Web Services Adapter earlier this year. At that time, we communicated a schedule for a couple of follow-on point releases (v1.1, v1.2 et cetera) over time, and I am pleased to annouce that v1.1 is now available for you to download (Go to the Scribe Download Page and follow the link entitiled "Updates").
In a previous post, Bob Sturim outlined what's coming in v1.1, so I won't reiterate that here. Instead I am going to focus on some features of the Web Services Adapter that will allow you to get the most out of Web Services.
Error Trapping and Reporting
The Web Service adapter is a general purpose "Technology" adapter. Adapters of this type (ODBC, XML, etc) report exceptions to the user based on what exceptions are "thrown" by the underlying technology. E.g. ODBC may throw an exception if you violate referential integrity; XML will throw an exception if your xml document is not properly formatted. In all these cases, the error is generated by the technology underneath Scribe (e.g. ODBC or XML) and is then "trapped" or "caught" by Scribe so that it can be presented to the user in a uniform way.
Similarly, the Web Service adapter will report any errors thrown by a web service. However, many Web Services communicate errors to consumers not by raising an exception, but by returning additional information via a return parameter instead. It is very common to have a Web Service perform work based on the inputs you supply and return the results of the work back to you. In other words, the Web Service may not perform the work and, if you are not listening for the response, you may be unaware that the work was not performed.
You can configure a Web Service Connection in Scribe to listen to the return value, and define a regular expression that would represent an "error condition" (e.g. if that regular expression is satisfied, then the execute step is considered to have failed). The Web Service Adapter help file has more information on how to do this (see "Reference > Catching unique exceptions").
Communicating across web method calls
When using a Web Service as a source, it's not uncommon for the Web Service to require that you provide some amount of information up front before it can return a results set that you can use as a source. This up-front information might be some sort of filtering/querying instructions, or security credentials. This can be done via the usual Source Configuration tools within Scribe. But what if the value returned from one Web Method call is to be used as an input to the next web method call...?
You can accommodate this scenario by defining and using a "Variable" while configuring a Web Service connection in Scribe. In the Web Service adapter, variables are marked as such by starting the value with either a percent sign ["%"] or colon [":"]. When you configure a Web Service connection, and you specify a value starting with a percent sign, the web service adapter will consider that to be a placeholder for a value to be defined later (currently, colons are used for predefined variables [e.g. :UserID and :Password for the user id and password as supplied by the user] and won't be covered in this entry.
Variables can be associated with [In] or [Out] parameter types. When associated with an [Out] type, the Web Service adapter will update the variable with the value returned. When associated with an [In] type, the value of the variable specified will be used for the parameter in question. The Web Service Adapter help file has more information about this topic (see "Reference > Runtime Variables").
In closing, let me add that we cannot get enough of your feedback! OpenMind (https://openmind.scribesoftware.com/ideas) is one of our primary means of gathering and "ranking" user feedback. See Bob Sturim's previous post for more information about OpenMind. If you are the shy type, feel free to contact me directly as well at the productmanagement email address I offered at the beginning of this post.
Tom O'Brien
Scribe Product Manager
Comments