The Duwamish Books, Phase 4 Workflow API Reference

Steve Kirk
Microsoft Developer Network

August 1999

Introduction

The Duwamish Books, Phase 4 Workflow API exposes COM and HTTP interfaces to provide Workflow services that support clients on diverse platforms. The Workflow API is implemented as a COM component, and as Active Server Pages (ASP) script.

The Duwamish Books, Phase 4 Workflow Layer (WFL) component is a COM component written in Microsoft® Visual Basic® that provides an XML wrapper around the Business Logic Layer (BLL) component API.

Server-side ASP scripts use the ASP object model, WFL component, cache component, the XML Document Object Model (XML DOM), and XSL style sheets to implement Workflow methods.

Duwamish Books, Phase 4 Workflow requires the following:

• The Duwamish Books, Phase 4 BLL COM component (see "The Duwamish Books, Phase 4 Business Logic Layer API Reference").
  
  
• The Duwamish Books, Phase 4 cache component, which is a COM component written in Microsoft Visual C++® with the Active Template Library (ATL) that provides high-performance caching of XML and HTML strings (see "The Duwamish Books, Phase 4 Cache Object API Reference").
  
  
• The Microsoft Internet Explorer 5 XML DOM object model, which provides XML parsing services and transformation services including XML-to-HTML transformation using XSL.

The Workflow Layer Component API

The Workflow Layer (WFL) component wraps the Business Logic Layer (BLL) API with an XML interface. The following methods are implemented.

GetAuthors(ByVal SearchText)

Description

Returns an XML search results list of Authors for SearchText.

Returned XML

<Search Type="SearchAuthor" SearchText="SearchText">
  <Author PKId="0" Authorname=""/>
…
</Search>

GetCategory(Optional ByVal CategoryId)

Description

Returns an XML representation of a Category for CategoryId. If CategoryId is not supplied or if CategoryId < 1, the root category specified by the RootCategory setting in the database Settings table is returned. If specified category is not found, an empty string is returned.

Returned XML

<CategoryChunk>
  <Category PKId="0" ParentId="0" Description="" IsLeaf="False" />
  <ParentCategory PKId="0" ParentId="0" Description="" IsLeaf="False" />
  <SubCategory PKId="0" ParentId="0" Description="" IsLeaf= False />
…
<Item PKId="0" SortOrder="0" ItemTypeId="0" PublisherId="0" SupplierId="0" PublicationYear="" ISBN="" ImageFileSpec="" Title="" Description="" UnitPrice="0.00" UnitCost="0.00" KeywordList="" ItemType="" IsBook="False" AuthorList=" " PublisherName="" SupplierName=""/>
…
</CategoryChunk>

GetCustomerByAlias(ByVal Alias)

Description

Returns an XML representation of Customer for Alias.

Returned XML

<Customer PKId="0" Alias="" Password="" CustomerName="" Email="" Address="" Country="" PhoneNumber="" Fax="" LastSale="01/01/1980" TotalSaleYTD="0.00"/>

GetItemByItemISBN(ByVal ISBN)

Description

Returns an XML representation of Item for ISBN.

Returned XML

<Search Type="SearchISBN" SearchText="ISBN">
  <Item PKId="0" ItemTypeId="0" PublisherId="0" SupplierId="0" PublicationYear="" ISBN="" ImageFileSpec="" Title="" Description="" UnitPrice="0.00" UnitCost="0.00" KeywordList="" ItemType=" " IsBook="False" AuthorList="" PublisherName="" SupplierName=""/>
</Search>

GetItemByItemId(ByVal ItemId)

Description

Returns an XML representation of Item for ItemId.

Returned XML

<Item PKId="0" ItemTypeId="0" PublisherId="0" SupplierId="0" PublicationYear="" ISBN="" ImageFileSpec=" " Title=" " Description="" UnitPrice="0.00" UnitCost="0.00" KeywordList="" ItemType="" IsBook="False" AuthorList="" PublisherName="" SupplierName="" AlsoPurchasedList=""/>

 GetItemsByAuthorKeywords(ByVal AuthorKeywordList)

Description

Returns an XML search results list of Items for AuthorKeywordList.

Returned XML

<Search Type="SearchAuthorKeyword" SearchText="AuthorKeywordList">
  <Item PKId="0" MatchLevel="0" ItemTypeId="0" PublisherId="0" SupplierId="0" PublicationYear="" ISBN="" ImageFileSpec="" Title="" Description="" UnitPrice="0.00" UnitCost="0.00" KeywordList="" ItemType="" IsBook="False" AuthorList="" PublisherName="" SupplierName=""/>
…
</Search>

GetItemsByItemIdList(ByVal ItemIdList)

Description

Returns an XML list of Items for ItemIdList.

Returned XML

<Items>
<Item PKId="0" ItemTypeId="0" PublisherId="0" SupplierId="0" PublicationYear="" ISBN="" ImageFileSpec="" Title="" Description="" UnitPrice="0.00" UnitCost="0.00" KeywordList="" ItemType="" IsBook="False" AuthorList="" PublisherName="" SupplierName=""/>
…
</Items>

GetItemsByNaturalLanguage(ByVal SearchText)

Description

Returns an XML search results list of Items for SearchText.

Returned XML

<Search Type="SearchNaturalLanguage" SearchText="SearchText">
  <Restated>SearchTextRestated</Restated>
  <Item PKId="0" ItemTypeId="0" PublisherId="0" SupplierId="0" PublicationYear="" ISBN="" ImageFileSpec="" Title="" Description="" UnitPrice="0.00" UnitCost="0.00" KeywordList="" ItemType="" IsBook="False" AuthorList="" PublisherName="" SupplierName=""/>
...
</Search>

GetItemsBySubjectKeywords(ByVal SubjectKeywordList)

Description

Returns an XML search results list of Items for SubjectKeywordList.

Returned XML

<Search Type="SearchSubjectKeyword" SearchText=" SubjectKeywordList">
  <Item PKId="0" MatchLevel="" ItemTypeId="0" PublisherId="0" SupplierId="0" PublicationYear="" ISBN="" ImageFileSpec="" Title="" Description="" UnitPrice="0.00" UnitCost="0.00" KeywordList="" ItemType="" IsBook="False" AuthorList="" PublisherName="" SupplierName=""/>
…
</Search>

GetItemsByTitle(ByVal Title)

Description

Returns an XML search results list of Items for Title.

Returned XML

<Search Type="SearchTitle" SearchText="Title">
  <Item PKId="0" ItemTypeId="0" PublisherId="0" SupplierId="0" PublicationYear="" ISBN="" ImageFileSpec="" Title="" Description="" UnitPrice="0.00" UnitCost="0.00" KeywordList="" ItemType="" IsBook="False" AuthorList="" PublisherName="" SupplierName=""/>

</Search>

GetItemsByTitleKeywords(ByVal TitleKeywordList)

Description

Returns an XML search results list of Items for TitleKeywordList.

Returned XML

<Search Type="SearchTitleKeyword" SearchText=" TitleKeywordList">
<Item PKId="0" MatchLevel="0" ItemTypeId="0" PublisherId="0" SupplierId="0" PublicationYear="" ISBN="" ImageFileSpec="" Title="" Description="" UnitPrice="0.00" UnitCost="0.00" KeywordList="" ItemType="" IsBook="False" AuthorList="" PublisherName="" SupplierName=""/>

</Search>

GetNewAccount(ByVal Alias)

Description

If supplied alias is unique, GetNewAccount returns an XML representation of a new Customer account for Alias. Returns empty string if Alias is already in use.

Returned XML

<Customer PKId="0" Alias="" Password="" CustomerName="" Email="" Address="" Country="" PhoneNumber="" Fax="" LastSale="01/01/1980" TotalSaleYTD="0.00"/>

GetOrders(ByVal CustomerId)

Description

Returns an XML list of Orders for CustomerId.

Returned XML

<Search Type="SearchCustomerOrders" SearchText="CustomerId">
  <Order PKId="0" CustomerId="0" EmployeeId="0" StoreId="0" OrderDate="1/1/1980" SubTotal="0.00" Tax="0.00" PaymentType="" CreditCardNumber="" ExpirationDate="" NameOnCard="" ApprovalCode="" Ship="True" OrderType="0" OrderStatus="0" ShippingHandling="0.00" ShipToName="" Address="" Country="" PhoneNumber="" Fax=""/>
…
</Search>

GetPayReq(ByVal XMLSaleContext)

Description

Returns an XML payment request to pass to payment service for XMLSaleContext.

XML Returned

XMLSaleContext is an XML representation of a sale prepared for InsertSale as follows:

<Sale HasCustomer="True" HasItems="True" HasPayment="False" HasShipping="True" HasSummary="True" >

<Customer PKId="0" Alias="" Password="" CustomerName="" Email="" Address="" Country="" PhoneNumber="" Fax="" LastSale="" TotalSaleYTD="0.00"/>

<Shipping Address="" ChkAddress="" />
<Summary SubTotal="0.00" Tax="0.00" Shipping="0.00" Total="0.00" />

<ShoppingCart>
  <Item ItemId="0" Title="" UnitPrice="0.00" Qty="0"/>
…
</ShoppingCart>
</Sale>

GetPayReq returns an XML representation of a payment authorization request to be passed to payment services object. The payment authorization request is similar to the following XML:

<PaymentAuthorizationRequest MerchantId="" TransactionId="0" TransactionAmount="0.00" TransactionCurrency=""/>"

GetSaleByTrackingId(ByVal TrackingId)

Description

Returns an XML representation of a Sale for TrackingId.

Returned XML

<Sale PKId="0" CustomerId="0" EmployeeId="0" StoreId="0" OrderDate="1/1/1980" SubTotal="0.00" Tax="0.00" PaymentType="" CreditCardNumber="" ExpirationDate="" NameOnCard="" ApprovalCode="" Ship="True" OrderType="0" OrderStatus="0" ShippingHandling="0.00" ShipToName="" Address="" Country="" PhoneNumber="" Fax="">
  <Detail PKId="0" OrderId="0" ItemId="0" UnitPrice="0.00" Quantity="0" Qty_Shipped="0" Notes=""/>
…
</Sale>

GetSession(Optional ByVal SessionId, _

Optional ByVal Alias, _

Optional ByVal Session)

Description

Returns data for SessionId and Alias wrapped in an XML representation of a session.

Replaces data for SessionId and Alias with contents of Session parameter if Session parameter <> "".

Creates a new contextual session in the back-end database and returns the SessionId if supplied SessionId and Alias do not match an already establishes contextual

Returned XML

<Session PKId="SessionId" Alias="Alias" />
  Session Data
…
</Session>

GetSettings(Optional ByVal Code)

Description

Returns an XML results list of all system Settings. If Code is supplied, GetSettings returns Setting for Code.

Returned XML

<Settings>
  <Setting Code="Code" Value="" Description=""/>
…
</Settings>

InsertSale(ByVal XMLWorkingSale)

Description

Inserts Sale for data in XMLWorkingSale. Returns TrackingId.

Returned XML

XMLWorkingSale is an XML representation of a sale prepared for InsertSale as follows:

<Sale HasCustomer="True" HasItems="True" HasPayment="False" HasShipping="True" HasSummary="True" >

<Customer PKId="0" Alias="" Password="" CustomerName="" Email="" Address="" Country="" PhoneNumber="" Fax="" LastSale="" TotalSaleYTD="0.00"/>

<Shipping Address="" ChkAddress="" />
<Summary SubTotal="0.00" Tax="0.00" Shipping="0.00" Total="0.00" />

<ShoppingCart>
  <Item ItemId="0" Title="" UnitPrice="0.00" Qty="0"/>
…
</ShoppingCart>
</Sale>

Returns:

<Sale PKId="0" Amount="0.00"/>

LogOnAccount(ByVal Alias, ByVal Password)

Description

Returns an XML representation of Customer for Alias and password.

Returned XML

<Customer PKId="0" Alias="Alias" Password="Password" CustomerName="" Email="" Address="" Country="" PhoneNumber="" Fax="" LastSale="1/1/1980" TotalSaleYTD="0.00"/>

UpdateCustomer(ByVal PKid, ByVal Alias, _

                                                        Optional ByVal Password, _

                                                        Optional ByVal CustomerName, _

                                                        Optional ByVal Address, _

                                                        Optional ByVal Country, _

                                                        Optional ByVal PhoneNumber, _

                                                        Optional ByVal Fax, _

                                                        Optional ByVal Email)

Description

Updates customer and returns an XML representation of Customer for PKId.

Returned XML

<Customer PKId="0" Alias="" Password="" CustomerName="" Email="" Address="" Country="" PhoneNumber="" Fax="" LastSale="1/1/1980" TotalSaleYTD=""/>

UpdateSaleApprovalCode(ByVal PKId, ByVal ApprovalCode) As Boolean

Description

Returns true on success and updates Sale ApprovalCode for PkId.

Workflow API Implemented in Script

Methods are listed by logical name along with implementation specifics.

GetSearchResults(SearchType, SearchText)

Returns advanced search results for SearchType and SearchText.

SearchType="SearchAuthor" calls WFL Component GetAuthors(SearchText)

SearchType="SearchISBN" calls WFL Component GetItemByItemISBN (SearchText)

SearchType="SearchNaturalLanguage" calls WFL Component GetItemsByNaturalLanguage (SearchText)

SearchType="SearchAuthorKeyword" calls WFL Component GetItemsByAuthorKeywords (SearchText)

SearchType="SearchSubjectKeyword" calls WFL Component GetItemsBySubjectKeywords (SearchText)

SearchType="SearchTitleKeyword" calls WFL Component GetItemsByTitleKeywords (SearchText)

SearchType="SearchTitle" calls WFL Component GetItemsByTitle(SearchText)

HTTP Post to \app1\sresults.asp
SearchType=""
SearchText=""

Returns HTML search results list with toolbar (XML from WFL component transformed using sresults.xsl).

HTTP Post to \app2\sresults.asp
SearchType=""
SearchText=""

Returns XML search results list from WFL component WFL component with script that applies XML to DSO.

HTTP Get from \app3\xmladvsch.asp?SearchType=SearchAuthor&SearchText=AuthorName
Returns XML search results list from WFL component.

GetSearchResults (Category, CategoryId)

Returns category list chunk for CategoryId.

HTTP Get from \app1\cat.asp?CategoryId
Returns HTML category list with toolbar.

Returns HTML from cache. Generates HTML and adds to cache if necessary (XML from WFL component transformed using cat.xsl).

HTTP Get from \app2\xmlcat.asp? CategoryId
Returns XML category list.

Returns XML from cache. Appends script that applies XML to DSO on load. Fetches XML from WFL component and adds to cache if necessary.

HTTP Get from \app3\xmlcat.asp? CategoryId
Returns XML category list.

Returns XML from cache. Fetches XML from WFL component and adds to cache if necessary.

GetItemDetail (ItemId)

Returns Item Detail for ItemId. Calls WFL component GetItemByItemId(ItemId).

HTTP Get from \app1\det.asp?ItemId
Returns HTML detail with toolbar.

Returns HTML from cache. Generates HTML and adds to cache if necessary (XML from WFL component transformed using det.xsl).

HTTP Get from \app2\det.asp?ItemId
Returns HTML detail.

Returns HTML from cache. Generates HTML and adds to cache if necessary (XML from WFL component transformed using det.xsl).

HTTP Get from \app3\xmldet.asp?ItemId
Returns XML detail.

Returns XML from cache. Fetches XML from WFL component and adds to cache if necessary.

GetOrder(OrderId)

Returns Order for OrderId.

HTTP Get from \app1\det.asp?ItemId
Returns HTML detail with toolbar.

Returns HTML from cache. Generates HTML and adds to cache if necessary (XML from WFL component transformed using det.xsl).

HTTP Get from \app2\det.asp?ItemId
Returns HTML detail.

Returns HTML from cache. Generates HTML and adds to cache if necessary (XML from WFL component transformed using det.xsl).

HTTP Get from \app3\xmldet.asp?ItemId
Returns XML detail.

Returns XML from cache. Fetches XML from WFL component and adds to cache if necessary.

Shopping Cart Methods

The following methods (from \common\d4wfl1a.asp) operate on the following XML representation of a Shopping Cart:

<ShoppingCart>
  <Item ItemId="0" Title="" UnitPrice="0.00" Qty="0"/>
…
</ShoppingCart>

AddToShoppingCart (ByVal ItemId, ByVal XMLShoppingCart)

Adds Item entity for ItemID to Shopping Cart and returns XML representation of Shopping Cart.

Increments item quantity by 1 if item is already in Shopping Cart.

UpdateShoppingCart (ByVal ItemId, ByVal Quantity, ByVal XMLShoppingCart)

Updates Shopping Cart for ItemId and Quantity and returns XML representation of Shopping Cart.

A Quantity of < 1 removes ItemId from Shopping Cart.

Comments? We welcome your feedback at duwamish@microsoft.com.